gruel_air/sema/

declarations.rs

//! Declaration gathering for semantic analysis.
//!
//! This module handles the first phase of semantic analysis: gathering all
//! type and function declarations from the RIR. This includes:
//!
//! - Registering struct and enum type names
//! - Resolving struct field types
//! - Collecting function signatures
//! - Collecting method signatures from impl blocks
//! - Validating @derive(Copy) and @handle structs

use rustc_hash::{FxHashMap as HashMap, FxHashSet as HashSet};

use gruel_builtins::{
    Abi, BUILTIN_MARKERS, ItemKinds, MarkerKind, Posture, ThreadSafety, get_builtin_marker,
    is_reserved_type_constructor_name,
};
use gruel_rir::{InstData, InstRef, RirParamMode};
use gruel_util::Span;
use gruel_util::{CompileError, CompileResult, ErrorKind, ice};
use lasso::Spur;

use super::anon_interfaces::decode_receiver_mode;
use super::{ConstInfo, FunctionInfo, InferenceContext, MethodInfo, Sema};
use crate::inference::{FunctionSig, MethodSig};
use crate::types::parse_type_call_syntax;
use crate::types::{
    EnumDef, EnumId, EnumVariantDef, InterfaceDef, InterfaceId, InterfaceMethodReq, ReceiverMode,
    StructDef, StructField, StructId, Type,
};

/// Posture declared by the user on a type definition (ADR-0080 / ADR-0083).
///
/// `Unmarked` is the default — the user did not write a `copy`/`linear`
/// keyword nor any `@mark(posture)` directive. Under uniform structural
/// inference (ADR-0083), unmarked types pick up their final posture from
/// their members; marked types must be consistent with the declaration.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum DeclaredPosture {
    Copy,
    Affine,
    Linear,
    Unmarked,
}

impl DeclaredPosture {
    fn as_str(self) -> &'static str {
        match self {
            DeclaredPosture::Copy => "copy",
            DeclaredPosture::Affine => "affine",
            DeclaredPosture::Linear => "linear",
            DeclaredPosture::Unmarked => "unmarked",
        }
    }
}

/// ADR-0083 / ADR-0084: outcome of processing the `@mark(...)` directive
/// list on a type declaration. Posture markers (`copy`/`affine`/`linear`)
/// and thread-safety markers (`unsend`/`checked_send`/`checked_sync`)
/// occupy independent slots — a type may carry one of each.
#[derive(Debug, Clone, Copy, Default)]
pub(crate) struct MarkOutcome {
    pub copy: bool,
    pub affine: bool,
    pub linear: bool,
    /// ADR-0084: thread-safety override (`unsend`, `checked_send`,
    /// `checked_sync`). At most one is permitted per directive list.
    /// Behind the `thread_safety` preview gate.
    pub thread_safety_override: Option<ThreadSafety>,
    /// ADR-0085: C ABI / C layout marker (`@mark(c)`). On a struct,
    /// switches layout to C rules and makes the type eligible to cross
    /// the FFI boundary by value. Behind the `c_ffi` preview gate.
    pub c_layout: bool,
}

/// Posture observed on a member's type (ADR-0080).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum MemberPosture {
    Copy,
    Affine,
    Linear,
}

impl MemberPosture {
    fn as_str(self) -> &'static str {
        match self {
            MemberPosture::Copy => "Copy",
            MemberPosture::Affine => "affine",
            MemberPosture::Linear => "linear",
        }
    }
}

/// ADR-0080 / ADR-0083: compare a member's posture against the host's
/// declared posture and produce a `PostureMismatch` error if the rule is
/// violated.
///
/// Rules:
///
/// - `Copy` host: every member must be Copy.
/// - `Affine` host (`@mark(affine)`): no member may be Linear (linear is
///   contagious upward and cannot be hidden behind an affine declaration,
///   ADR-0083).
/// - `Linear` host: accepts anything.
/// - `Unmarked`: no constraint here — under uniform inference the final
///   posture is the inferred posture, never an error.
fn check_posture_against_declared(
    host_kind: &'static str,
    host_name: &str,
    declared: DeclaredPosture,
    member_kind: &'static str,
    member_name: &str,
    member_type: &str,
    member_posture: MemberPosture,
    span: Span,
) -> Option<CompileError> {
    let violates = matches!(
        (declared, member_posture),
        (
            DeclaredPosture::Copy,
            MemberPosture::Affine | MemberPosture::Linear
        ) | (DeclaredPosture::Affine, MemberPosture::Linear)
    );
    if !violates {
        return None;
    }
    Some(CompileError::new(
        ErrorKind::PostureMismatch(Box::new(gruel_util::PostureMismatchError {
            host_kind,
            host_name: host_name.to_string(),
            declared_posture: declared.as_str(),
            member_kind,
            member_name: member_name.to_string(),
            member_type: member_type.to_string(),
            member_posture: member_posture.as_str(),
        })),
        span,
    ))
}

/// Signature data for a `drop` method, bundled for inline-drop registration.
struct DropSignature {
    has_self: bool,
    params_len: u32,
    return_type: Spur,
    body: InstRef,
    span: Span,
}

/// Visibility / safety flags on a top-level function declaration.
#[derive(Clone, Copy)]
struct FnFlags {
    is_pub: bool,
    is_unchecked: bool,
    /// Index into the extra array where this fn's directives start
    /// (ADR-0085: used to detect `@mark(c)` / `@link_name(...)`).
    directives_start: u32,
    /// Number of directives.
    directives_len: u32,
}

impl<'a> Sema<'a> {
    /// Build an `InferenceContext` from the collected type information.
    ///
    /// This should be called after the collection phase and builds the
    /// pre-computed maps needed for Hindley-Milner type inference.
    /// Building this once and reusing for all function analyses avoids
    /// the O(n²) cost of rebuilding these maps per function.
    ///
    /// # Performance
    ///
    /// This converts all function/method signatures to use `InferType`
    /// (which handles arrays structurally rather than by ID). This conversion
    /// is done once instead of per-function.
    pub fn build_inference_context(&self) -> InferenceContext {
        // Build function signatures with InferType for constraint generation
        let func_sigs: HashMap<Spur, FunctionSig> = self
            .functions
            .iter()
            .map(|(name, info)| {
                (
                    *name,
                    FunctionSig {
                        param_types: self
                            .param_arena
                            .types(info.params)
                            .iter()
                            .map(|t| self.type_to_infer_type(*t))
                            .collect(),
                        return_type: self.type_to_infer_type(info.return_type),
                        is_generic: info.is_generic,
                        param_modes: self.param_arena.modes(info.params).to_vec(),
                        param_comptime: self.param_arena.comptime(info.params).to_vec(),
                        param_names: self.param_arena.names(info.params).to_vec(),
                        return_type_sym: info.return_type_sym,
                    },
                )
            })
            .collect();

        // Build struct types map (name -> Type::new_struct(id))
        let struct_types: HashMap<Spur, Type> = self
            .structs
            .iter()
            .map(|(name, id)| (*name, Type::new_struct(*id)))
            .collect();

        // Build enum types map (name -> Type::new_enum(id))
        let enum_types: HashMap<Spur, Type> = self
            .enums
            .iter()
            .map(|(name, id)| (*name, Type::new_enum(*id)))
            .collect();

        // Build method signatures with InferType for constraint generation.
        // Method-level-generic methods (ADR-0055) are excluded: their stored
        // `return_type` is a `COMPTIME_TYPE` placeholder, and their param
        // types may reference unresolved method-level type params. The
        // inference pass falls back to fresh type variables for calls to
        // these methods, and the specialized bodies (synthesized by
        // `specialize::create_specialized`) are analyzed separately with the
        // concrete substitutions in place.
        let method_sigs: HashMap<(StructId, Spur), MethodSig> = self
            .methods
            .iter()
            .filter(|(_, info)| !info.is_generic)
            .map(|((struct_id, method_name), info)| {
                (
                    (*struct_id, *method_name),
                    MethodSig {
                        struct_type: info.struct_type,
                        has_self: info.has_self,
                        param_types: self
                            .param_arena
                            .types(info.params)
                            .iter()
                            .map(|t| self.type_to_infer_type(*t))
                            .collect(),
                        return_type: self.type_to_infer_type(info.return_type),
                    },
                )
            })
            .collect();

        // Build enum method signatures for constraint generation
        let enum_method_sigs: HashMap<(EnumId, Spur), MethodSig> = self
            .enum_methods
            .iter()
            .map(|((enum_id, method_name), info)| {
                (
                    (*enum_id, *method_name),
                    MethodSig {
                        struct_type: info.struct_type,
                        has_self: info.has_self,
                        param_types: self
                            .param_arena
                            .types(info.params)
                            .iter()
                            .map(|t| self.type_to_infer_type(*t))
                            .collect(),
                        return_type: self.type_to_infer_type(info.return_type),
                    },
                )
            })
            .collect();

        InferenceContext {
            func_sigs,
            struct_types,
            enum_types,
            method_sigs,
            enum_method_sigs,
        }
    }
    // ADR-0080 retired `has_copy_directive`: `@derive(Copy)` no longer
    // resolves to a known interface, so the directive falls through the
    // existing "unknown interface" derive resolver path.

    /// ADR-0075: walk every directive collected during parsing and reject any
    /// whose name isn't in the recognized set (`@allow`, `@derive`). Retired
    /// directives (`@handle`, `@copy`) get a targeted retirement note; other
    /// unknowns get an edit-distance suggestion when there's a near-match.
    pub(crate) fn validate_directives(&self) -> CompileResult<()> {
        for (_, inst) in self.rir.iter() {
            let (start, len, _is_fn_decl) = match &inst.data {
                InstData::StructDecl {
                    directives_start,
                    directives_len,
                    ..
                }
                | InstData::Alloc {
                    directives_start,
                    directives_len,
                    ..
                }
                | InstData::ConstDecl {
                    directives_start,
                    directives_len,
                    ..
                }
                | InstData::AnonStructType {
                    directives_start,
                    directives_len,
                    ..
                }
                | InstData::AnonEnumType {
                    directives_start,
                    directives_len,
                    ..
                } => (*directives_start, *directives_len, false),
                InstData::FnDecl {
                    directives_start,
                    directives_len,
                    ..
                } => (*directives_start, *directives_len, true),
                _ => continue,
            };
            if len == 0 {
                continue;
            }
            for directive in self.rir.get_directives(start, len) {
                let name = self.interner.resolve(&directive.name).to_string();
                if name == "allow"
                    || name == "derive"
                    || name == "lang"
                    || name == "mark"
                    || name == "link_name"
                {
                    continue;
                }
                let note = directive_diagnosis_note(&name);
                return Err(CompileError::new(
                    ErrorKind::UnknownDirective { name, note },
                    directive.span,
                ));
            }
        }
        Ok(())
    }

    /// Phase 1: Register all type names (enum and struct IDs).
    ///
    /// This creates name → ID mappings for all enums and structs in a single pass,
    /// allowing types to reference each other in any order. Struct definitions are
    /// created with placeholder empty fields that will be filled in during phase 2.
    /// Validate and register `interface` declarations (ADR-0056).
    ///
    /// - Gates each declaration behind the `interfaces` preview feature.
    /// - Rejects duplicate method names within a single interface.
    /// - Rejects collisions between interface names and existing structs/enums
    ///   (and other interfaces).
    /// - Resolves each method signature's parameter and return types and
    ///   stores an `InterfaceDef` on `Sema`.
    ///
    /// Conformance and dispatch wiring land in later phases.
    pub(crate) fn validate_interface_decls(&mut self) -> CompileResult<()> {
        // Two-pass walk: first collect raw decls (snapshotting RIR data so we
        // can mutate Sema while resolving types), then register each one.
        struct RawIface {
            name: Spur,
            is_pub: bool,
            file_id: gruel_util::FileId,
            decl_span: Span,
            methods: Vec<RawIfaceMethod>,
        }
        struct RawIfaceMethod {
            name: Spur,
            params: Vec<(Spur, Spur)>, // (param_name, type_symbol)
            return_type_sym: Spur,
            receiver: ReceiverMode,
            /// ADR-0088: whether this interface method signature is
            /// `@mark(unchecked)`.
            is_unchecked: bool,
            span: Span,
        }

        let mut raw: Vec<RawIface> = Vec::new();
        for (_, inst) in self.rir.iter() {
            if let InstData::InterfaceDecl {
                is_pub,
                name,
                methods_start,
                methods_len,
                directives_start,
                directives_len,
            } = &inst.data
            {
                // ADR-0088: `@mark(...)` is not legal on interface
                // declaration heads. Interfaces don't carry ABI
                // (`@mark(c)`), posture (`@mark(copy|affine|linear)`),
                // thread-safety overrides, or per-fn `@mark(unchecked)`
                // — those all attach to fn / struct / enum
                // declarations. `@lang("…")` is the only directive
                // currently legal on an interface head.
                let directives = self.rir.get_directives(*directives_start, *directives_len);
                for d in directives.iter() {
                    if self.interner.resolve(&d.name) != "mark" {
                        continue;
                    }
                    // Any `@mark(arg)` on an interface head is rejected
                    // — surface the first arg's name in the diagnostic.
                    if let Some(arg) = d.args.first() {
                        let arg_name = self.interner.resolve(arg);
                        return Err(CompileError::new(
                            ErrorKind::MarkerNotApplicable {
                                marker: arg_name.to_string(),
                                item_kind: "interface",
                            },
                            d.span,
                        ));
                    }
                }
                let method_refs = self.rir.get_inst_refs(*methods_start, *methods_len);
                let mut seen: HashSet<Spur> = HashSet::default();
                let mut methods = Vec::new();
                for method_ref in method_refs {
                    let m = self.rir.get(method_ref);
                    if let InstData::InterfaceMethodSig {
                        name: method_name,
                        params_start,
                        params_len,
                        return_type,
                        receiver_mode,
                        is_unchecked,
                        directives_start,
                        directives_len,
                    } = &m.data
                    {
                        if !seen.insert(*method_name) {
                            let iface_name = self.interner.resolve(name).to_string();
                            let method_name_str = self.interner.resolve(method_name).to_string();
                            return Err(CompileError::new(
                                ErrorKind::DuplicateMethod {
                                    type_name: format!("interface `{}`", iface_name),
                                    method_name: method_name_str,
                                },
                                m.span,
                            ));
                        }

                        // ADR-0088: only `@mark(unchecked)` is legal on
                        // interface method signatures. Reject any other
                        // marker (e.g. `@mark(c)`, `@mark(copy)`).
                        let method_directives =
                            self.rir.get_directives(*directives_start, *directives_len);
                        for d in method_directives.iter() {
                            if self.interner.resolve(&d.name) != "mark" {
                                continue;
                            }
                            for arg in &d.args {
                                let arg_name = self.interner.resolve(arg);
                                if arg_name != "unchecked" {
                                    return Err(CompileError::new(
                                        ErrorKind::MarkerNotApplicable {
                                            marker: arg_name.to_string(),
                                            item_kind: "interface method",
                                        },
                                        d.span,
                                    ));
                                }
                            }
                        }
                        let params = self
                            .rir
                            .get_params(*params_start, *params_len)
                            .into_iter()
                            .map(|p| (p.name, p.ty))
                            .collect();
                        let receiver = match *receiver_mode {
                            1 => ReceiverMode::MutRef,
                            2 => ReceiverMode::Ref,
                            _ => ReceiverMode::ByValue,
                        };
                        methods.push(RawIfaceMethod {
                            name: *method_name,
                            params,
                            return_type_sym: *return_type,
                            receiver,
                            is_unchecked: *is_unchecked,
                            span: m.span,
                        });
                    }
                }

                raw.push(RawIface {
                    name: *name,
                    is_pub: *is_pub,
                    file_id: inst.span.file_id,
                    decl_span: inst.span,
                    methods,
                });
            }
        }

        for r in raw {
            // Reject collision with existing structs/enums/interfaces.
            let name_str = self.interner.resolve(&r.name).to_string();
            if self.structs.contains_key(&r.name)
                || self.enums.contains_key(&r.name)
                || self.interfaces.contains_key(&r.name)
            {
                return Err(CompileError::new(
                    ErrorKind::DuplicateTypeDefinition {
                        type_name: format!("interface `{}`", name_str),
                    },
                    r.decl_span,
                ));
            }

            // Resolve each method's parameter and return slots, recognizing
            // the symbol `Self` as `IfaceTy::SelfType` (ADR-0060). Receiver
            // mode is `ByValue` until Phase 2 threads `inout`/`borrow self`
            // from the parser.
            let mut resolved_methods = Vec::with_capacity(r.methods.len());
            for m in &r.methods {
                let mut param_types = Vec::with_capacity(m.params.len());
                for (_pname, ty_sym) in &m.params {
                    param_types.push(self.resolve_iface_ty(*ty_sym, m.span)?);
                }
                let return_type = self.resolve_iface_ty(m.return_type_sym, m.span)?;
                resolved_methods.push(InterfaceMethodReq {
                    name: self.interner.resolve(&m.name).to_string(),
                    receiver: m.receiver,
                    param_types,
                    return_type,
                    is_unchecked: m.is_unchecked,
                });
            }

            let id = InterfaceId(self.interface_defs.len() as u32);
            self.interface_defs.push(InterfaceDef {
                name: name_str,
                methods: resolved_methods,
                is_pub: r.is_pub,
                file_id: r.file_id,
            });
            self.interfaces.insert(r.name, id);
        }

        Ok(())
    }

    pub(crate) fn register_type_names(&mut self) -> CompileResult<()> {
        for (_, inst) in self.rir.iter() {
            match &inst.data {
                InstData::EnumDecl {
                    is_pub,
                    name,
                    variants_start,
                    variants_len,
                    directives_start,
                    directives_len,
                    ..
                } => {
                    let enum_name = self.interner.resolve(name).to_string();

                    // ADR-0083 Phase 4: posture is declared exclusively via
                    // the `@mark(...)` directive — the keyword path retired.
                    // `@mark(affine)` is tracked separately on `MarkOutcome`
                    // because `Posture::Affine` is the default and the
                    // marker existing affects later inference suppression.
                    let mark_outcome = self.process_mark_directives(
                        *directives_start,
                        *directives_len,
                        "enum",
                        ItemKinds::ENUM,
                        inst.span,
                    )?;

                    if mark_outcome.copy && mark_outcome.linear {
                        return Err(CompileError::new(
                            ErrorKind::LinearStructCopy(enum_name.clone()),
                            inst.span,
                        ));
                    }
                    // ADR-0083: `@mark(affine)` cannot coexist with Copy or
                    // Linear declarations.
                    if mark_outcome.affine && (mark_outcome.copy || mark_outcome.linear) {
                        return Err(CompileError::new(
                            ErrorKind::LinearStructCopy(enum_name.clone()),
                            inst.span,
                        ));
                    }
                    let posture = if mark_outcome.copy {
                        Posture::Copy
                    } else if mark_outcome.linear {
                        Posture::Linear
                    } else {
                        Posture::Affine
                    };

                    // Check for collision with built-in type constructors
                    // (e.g. Ptr, MutPtr — see ADR-0061). ADR-0081 retired
                    // the BUILTIN_TYPES registry; collisions with prelude
                    // types are caught by the duplicate-type check below.
                    if is_reserved_type_constructor_name(&enum_name) {
                        return Err(CompileError::new(
                            ErrorKind::ReservedTypeName {
                                type_name: enum_name,
                            },
                            inst.span,
                        ));
                    }

                    // Check for duplicate type definitions (struct or enum with same name)
                    if self.enums.contains_key(name) || self.structs.contains_key(name) {
                        return Err(CompileError::new(
                            ErrorKind::DuplicateTypeDefinition {
                                type_name: enum_name,
                            },
                            inst.span,
                        ));
                    }

                    let raw_variants = self
                        .rir
                        .get_enum_variant_decls(*variants_start, *variants_len);

                    // Check for duplicate variant names
                    let mut seen_variants: HashSet<Spur> = HashSet::default();
                    for (variant_name, _, field_names) in &raw_variants {
                        if !seen_variants.insert(*variant_name) {
                            let variant_name_str = self.interner.resolve(variant_name).to_string();
                            return Err(CompileError::new(
                                ErrorKind::DuplicateVariant {
                                    enum_name: enum_name.clone(),
                                    variant_name: variant_name_str,
                                },
                                inst.span,
                            ));
                        }

                        if !field_names.is_empty() {
                            // Check for duplicate field names within the struct variant
                            let variant_str = self.interner.resolve(variant_name).to_string();
                            let mut seen_fields: HashSet<Spur> = HashSet::default();
                            for field_name in field_names {
                                if !seen_fields.insert(*field_name) {
                                    let field_str = self.interner.resolve(field_name).to_string();
                                    return Err(CompileError::new(
                                        ErrorKind::DuplicateField {
                                            struct_name: format!("{}::{}", enum_name, variant_str),
                                            field_name: field_str,
                                        },
                                        inst.span,
                                    ));
                                }
                            }
                        }
                    }

                    // Build EnumVariantDef list. Field types are stored as unit for now;
                    // full type resolution will be added in later phases when we
                    // lower them through the type checker.
                    let variants: Vec<EnumVariantDef> = raw_variants
                        .iter()
                        .map(|(vname, _fields, field_names)| EnumVariantDef {
                            name: self.interner.resolve(vname).to_string(),
                            fields: Vec::new(), // Field types resolved in later phases
                            field_names: field_names
                                .iter()
                                .map(|n| self.interner.resolve(n).to_string())
                                .collect(),
                        })
                        .collect();

                    let enum_def = EnumDef {
                        name: enum_name,
                        variants,
                        posture,
                        // ADR-0084: placeholder. The structural minimum
                        // and any `@mark(...)` override are folded in
                        // by `validate_consistency` once fields resolve.
                        // Defaulting to the user's explicit override (if
                        // any) lets `is_thread_safety_type` give a sane
                        // answer in the rare cases that consult the
                        // field before the inference pass runs.
                        thread_safety: mark_outcome
                            .thread_safety_override
                            .unwrap_or(ThreadSafety::Sync),
                        is_pub: *is_pub,
                        file_id: inst.span.file_id,
                        destructor: None,
                        // ADR-0086: `@mark(c)` flag flows from the
                        // directive walker via `mark_outcome.c_layout`.
                        is_c_layout: mark_outcome.c_layout,
                    };

                    // Register in type pool and get pool-based EnumId
                    let (enum_id, _) = self.type_pool.register_enum(*name, enum_def);

                    // Register in enum lookup with pool-based EnumId
                    self.enums.insert(*name, enum_id);

                    if mark_outcome.affine {
                        self.mark_affine_decls.insert(*name);
                    }
                    // ADR-0084: track thread-safety overrides so
                    // `validate_consistency` can apply them after
                    // computing the structural minimum.
                    if let Some(level) = mark_outcome.thread_safety_override {
                        self.mark_thread_safety_decls.insert(*name, level);
                    }
                }
                InstData::StructDecl {
                    directives_start,
                    directives_len,
                    is_pub,
                    name,
                    ..
                } => {
                    let struct_name = self.interner.resolve(name).to_string();

                    // Check for collision with built-in type constructors
                    // (e.g. Ptr, MutPtr — see ADR-0061). ADR-0081 retired
                    // the BUILTIN_TYPES registry; collisions with prelude
                    // types are caught by the duplicate-type check below.
                    if is_reserved_type_constructor_name(&struct_name) {
                        return Err(CompileError::new(
                            ErrorKind::ReservedTypeName {
                                type_name: struct_name,
                            },
                            inst.span,
                        ));
                    }

                    // Check for duplicate type definitions (struct or enum with same name)
                    if self.structs.contains_key(name) || self.enums.contains_key(name) {
                        return Err(CompileError::new(
                            ErrorKind::DuplicateTypeDefinition {
                                type_name: struct_name,
                            },
                            inst.span,
                        ));
                    }

                    // ADR-0083 Phase 4: posture is declared exclusively via
                    // the `@mark(...)` directive — the keyword path retired.
                    let mark_outcome = self.process_mark_directives(
                        *directives_start,
                        *directives_len,
                        "struct",
                        ItemKinds::STRUCT,
                        inst.span,
                    )?;

                    // Linear types cannot be Copy.
                    if mark_outcome.linear && mark_outcome.copy {
                        return Err(CompileError::new(
                            ErrorKind::LinearStructCopy(struct_name.clone()),
                            inst.span,
                        ));
                    }
                    if mark_outcome.affine && (mark_outcome.copy || mark_outcome.linear) {
                        return Err(CompileError::new(
                            ErrorKind::LinearStructCopy(struct_name.clone()),
                            inst.span,
                        ));
                    }
                    let posture = if mark_outcome.copy {
                        Posture::Copy
                    } else if mark_outcome.linear {
                        Posture::Linear
                    } else {
                        Posture::Affine
                    };

                    // Create placeholder struct def (fields will be resolved in phase 2)
                    let struct_def = StructDef {
                        name: struct_name,
                        fields: Vec::new(), // Filled in during resolve_declarations
                        posture,
                        is_clone: false, // Filled in during resolve_declarations after fields known
                        // ADR-0084: see EnumDecl above for rationale.
                        thread_safety: mark_outcome
                            .thread_safety_override
                            .unwrap_or(ThreadSafety::Sync),
                        destructor: None,  // Filled in during resolve_declarations
                        is_builtin: false, // User-defined struct
                        is_pub: *is_pub,
                        file_id: inst.span.file_id,
                        // ADR-0085: track whether `@mark(c)` was applied.
                        is_c_layout: mark_outcome.c_layout,
                    };

                    // Register in type pool and get pool-based StructId
                    let (struct_id, _) = self.type_pool.register_struct(*name, struct_def);

                    // Register in struct lookup with pool-based StructId
                    self.structs.insert(*name, struct_id);

                    if mark_outcome.affine {
                        self.mark_affine_decls.insert(*name);
                    }
                    // ADR-0084: track thread-safety overrides — see
                    // EnumDecl above.
                    if let Some(level) = mark_outcome.thread_safety_override {
                        self.mark_thread_safety_decls.insert(*name, level);
                    }
                }
                _ => {}
            }
        }
        Ok(())
    }

    /// ADR-0083 / ADR-0084: apply `@mark(...)` directives recorded on
    /// an anonymous struct expression to its already-created `StructDef`.
    /// Mirrors what `validate_consistency` does for named declarations:
    /// reads the marker outcome, then writes posture and thread-safety
    /// fields. Called from the comptime evaluator and analysis paths
    /// after `find_or_create_anon_struct` returns a fresh `StructId`.
    pub(crate) fn apply_anon_struct_marks(
        &mut self,
        struct_id: StructId,
        directives_start: u32,
        directives_len: u32,
        span: Span,
    ) -> CompileResult<()> {
        let outcome = self.process_mark_directives(
            directives_start,
            directives_len,
            "struct",
            ItemKinds::STRUCT,
            span,
        )?;
        let mut def = self.type_pool.struct_def(struct_id);
        // Posture: a marker overrides the structurally-inferred posture
        // that `find_or_create_anon_struct` set.
        if outcome.copy {
            def.posture = Posture::Copy;
        }
        if outcome.linear {
            def.posture = Posture::Linear;
        }
        if outcome.affine {
            def.posture = Posture::Affine;
        }
        // Thread-safety: marker wins over the structural minimum the
        // anon-struct constructor pre-computed.
        if let Some(level) = outcome.thread_safety_override {
            def.thread_safety = level;
        }
        self.type_pool.update_struct_def(struct_id, def);
        Ok(())
    }

    /// Same as `apply_anon_struct_marks`, but for anonymous enums
    /// (variant-payload structural fold + override).
    pub(crate) fn apply_anon_enum_marks(
        &mut self,
        enum_id: EnumId,
        directives_start: u32,
        directives_len: u32,
        span: Span,
    ) -> CompileResult<()> {
        let outcome = self.process_mark_directives(
            directives_start,
            directives_len,
            "enum",
            ItemKinds::ENUM,
            span,
        )?;
        let mut def = self.type_pool.enum_def(enum_id);
        if outcome.copy {
            def.posture = Posture::Copy;
        }
        if outcome.linear {
            def.posture = Posture::Linear;
        }
        if outcome.affine {
            def.posture = Posture::Affine;
        }
        if let Some(level) = outcome.thread_safety_override {
            def.thread_safety = level;
        }
        self.type_pool.update_enum_def(enum_id, def);
        Ok(())
    }

    /// ADR-0083: process the `@mark(...)` directives on a type declaration.
    ///
    /// Walks the directive list and validates each marker against the
    /// `BUILTIN_MARKERS` registry. Returns a flag-set describing which
    /// posture markers were declared so the caller can fold them into the
    /// type's `posture` field (and the `mark_affine_decls`
    /// side set).
    ///
    /// Errors out on:
    /// - Unknown markers (with edit-distance suggestions).
    /// - Markers not applicable to the host item kind.
    /// - Conflicting posture markers within the same directive list (e.g.
    ///   `@mark(copy)` + `@mark(linear)`).
    /// - Conflicting thread-safety markers (e.g. `@mark(unsend)` +
    ///   `@mark(checked_send)`) — ADR-0084.
    /// - Use of a thread-safety marker without `--preview thread_safety`.
    pub(crate) fn process_mark_directives(
        &self,
        directives_start: u32,
        directives_len: u32,
        item_kind_name: &'static str,
        item_kind: ItemKinds,
        span: Span,
    ) -> CompileResult<MarkOutcome> {
        let mut outcome = MarkOutcome::default();
        if directives_len == 0 {
            return Ok(outcome);
        }
        let directives = self.rir.get_directives(directives_start, directives_len);
        for directive in directives.iter() {
            let dir_name = self.interner.resolve(&directive.name);
            if dir_name != "mark" {
                continue;
            }
            if directive.args.is_empty() {
                return Err(CompileError::new(
                    ErrorKind::UnknownMarker {
                        name: String::new(),
                        note: Some(format!(
                            "`@mark(...)` requires at least one marker name; valid markers: {}",
                            BUILTIN_MARKERS
                                .iter()
                                .map(|m| m.name)
                                .collect::<Vec<_>>()
                                .join(", ")
                        )),
                    },
                    directive.span,
                ));
            }
            for arg in &directive.args {
                let marker_name = self.interner.resolve(arg).to_string();
                let marker = match get_builtin_marker(&marker_name) {
                    Some(m) => m,
                    None => {
                        let note = marker_diagnosis_note(&marker_name);
                        return Err(CompileError::new(
                            ErrorKind::UnknownMarker {
                                name: marker_name,
                                note,
                            },
                            directive.span,
                        ));
                    }
                };
                let applicable = match item_kind {
                    k if k == ItemKinds::STRUCT => marker.applicable_to.includes_struct(),
                    k if k == ItemKinds::ENUM => marker.applicable_to.includes_enum(),
                    _ => true,
                };
                if !applicable {
                    return Err(CompileError::new(
                        ErrorKind::MarkerNotApplicable {
                            marker: marker.name.to_string(),
                            item_kind: item_kind_name,
                        },
                        directive.span,
                    ));
                }
                match marker.kind {
                    MarkerKind::Posture(Posture::Copy) => outcome.copy = true,
                    MarkerKind::Posture(Posture::Affine) => outcome.affine = true,
                    MarkerKind::Posture(Posture::Linear) => outcome.linear = true,
                    MarkerKind::ThreadSafety(level) => {
                        // ADR-0084: thread-safety markers stabilized
                        // — no preview gate after Phase 7.
                        if let Some(prev) = outcome.thread_safety_override
                            && prev != level
                        {
                            return Err(CompileError::new(
                                ErrorKind::ConflictingThreadSafetyMarkers {
                                    type_name: item_kind_name.to_string(),
                                },
                                span,
                            ));
                        }
                        outcome.thread_safety_override = Some(level);
                    }
                    MarkerKind::Abi(Abi::C) => {
                        // ADR-0085 stabilised `@mark(c)` on fns / structs;
                        // ADR-0086 stabilised it on enums. The marker is
                        // already known to be applicable to the host item
                        // kind by this point.
                        outcome.c_layout = true;
                    }
                    MarkerKind::Unchecked => {
                        // ADR-0088: `@mark(unchecked)` only applies to
                        // fn-like declarations. The marker registry's
                        // `applicable_to` field already filters this out
                        // for struct/enum decls, but if we get here on a
                        // non-fn item we surface the not-applicable
                        // error rather than silently dropping it.
                        return Err(CompileError::new(
                            ErrorKind::MarkerNotApplicable {
                                marker: marker.name.to_string(),
                                item_kind: item_kind_name,
                            },
                            directive.span,
                        ));
                    }
                }
            }
        }
        // Mutual exclusion across all `@mark` directives on this item.
        let posture_count = (outcome.copy as u8) + (outcome.affine as u8) + (outcome.linear as u8);
        if posture_count > 1 {
            // Reuse the existing `LinearStructCopy` diagnostic spelling for
            // Copy + Linear; for the rarer Copy + Affine / Affine + Linear
            // combinations we still want a clear error, so we fall back to
            // the same kind with a generic name placeholder.
            return Err(CompileError::new(
                ErrorKind::LinearStructCopy("<conflicting `@mark(...)` markers>".to_string()),
                span,
            ));
        }
        Ok(outcome)
    }

    /// Phase 2: Resolve all declarations.
    ///
    /// Now that all type names are registered, this resolves:
    /// - Struct field types (must be done first for @derive(Copy) validation)
    /// - @derive(Copy) struct validation, destructors, functions, and methods
    ///
    /// # Array Type Registration
    ///
    /// Array types from explicit type annotations (struct fields, function parameters,
    /// return types, local variable annotations) are registered during this phase via
    /// `resolve_type()` calls. Array types from literals (inferred during HM inference)
    /// are created on-demand via the thread-safe `TypeInternPool` during function
    /// body analysis.
    pub(crate) fn resolve_declarations(&mut self) -> CompileResult<()> {
        // ADR-0075: surface unrecognized `@name` directives before any
        // downstream pass that would silently ignore them.
        self.validate_directives()?;
        // Derives (ADR-0058) are gated by the `comptime_derives` preview
        // feature. Reject any `derive` item before we touch the rest of
        // declaration gathering so users get a clear diagnostic.
        self.validate_derive_decls()?;
        // Interfaces (ADR-0056) must be registered before struct/enum field
        // and method-param resolution so that:
        //   - using an interface name as a struct field type produces a
        //     helpful diagnostic redirecting to the comptime path
        //   - `comptime T: SomeInterface` bounds are recognized when
        //     functions and methods are gathered
        //   - `borrow t: SomeInterface` parameter types resolve correctly
        self.validate_interface_decls()?;
        // ADR-0079: bind `@lang("…")` directives in the prelude to
        // interface/enum IDs. Must run after interfaces are registered
        // and before any sema pass that consults `lang_items`. Enum
        // bindings only resolve once `register_type_names` has populated
        // `self.enums`, which already happened in Phase 1.
        self.populate_lang_items()?;
        self.resolve_struct_fields()?;
        self.resolve_enum_variant_fields()?;
        // ADR-0080 Phase 3: validate that each named declaration's
        // declared posture (`copy` / unmarked / `linear`) is consistent
        // with the postures of its fields/variants. Runs after field
        // resolution so member types are populated. Anonymous types are
        // checked at construction time (see `find_or_create_anon_struct`
        // / `find_or_create_anon_enum`).
        self.validate_consistency()?;
        // ADR-0058 sub-phase: resolve every `@derive(D)` directive on a
        // named struct or enum into a binding for the upcoming expansion
        // step. Runs after field-type resolution so the host type is
        // already fully known.
        self.resolve_derive_directives()?;
        // ADR-0058 sub-phase: splice every `(host_type, derive_id)`
        // binding's methods into the host's method list. Runs after the
        // host's fields are known so destructor / Copy validation
        // (`resolve_remaining_declarations`) sees the attached methods.
        self.expand_derives()?;
        self.resolve_remaining_declarations()?;
        Ok(())
    }

    /// Phase 4 of ADR-0058: walk every recorded `DeriveBinding` and splice
    /// the named derive's methods into the host type's method list. The
    /// same routine is reused at the anonymous-host call site (see
    /// `splice_derive_methods_into_struct`).
    pub(crate) fn expand_derives(&mut self) -> CompileResult<()> {
        // Snapshot the bindings so we can iterate while mutating
        // `self.methods`. Bindings are restored after expansion so the
        // analysis loop can drive each spliced method's body analysis.
        let bindings = self.derive_bindings.clone();
        for b in &bindings {
            // Anonymous-host expansion uses a different call site; named
            // bindings always carry a `host_name` that resolves through
            // `self.structs` (or, in the future, `self.enums`).
            if b.host_is_enum {
                let enum_id = match self.enums.get(&b.host_name).copied() {
                    Some(id) => id,
                    None => continue,
                };
                self.splice_derive_methods_into_enum(b.derive_name, enum_id, b.directive_span)?;
            } else {
                let struct_id = match self.structs.get(&b.host_name).copied() {
                    Some(id) => id,
                    None => continue,
                };
                self.splice_derive_methods_into_struct(b.derive_name, struct_id, b.directive_span)?;
            }
        }
        // Replace the (now-consumed) bindings — the cloned working set is
        // already done. Phase 4 keeps the original list around for the
        // analysis loop to drive body analysis later.
        self.derive_bindings = bindings;
        Ok(())
    }

    /// Anonymous-host call site for ADR-0058: walk an anonymous-struct
    /// expression's `@derive(...)` directives and splice each derive's
    /// methods into the freshly-built host. Should be called exactly once
    /// per new anonymous `StructId` (the structural-dedup path skips this).
    pub(crate) fn splice_anon_struct_derives(
        &mut self,
        host_id: StructId,
        directives_start: u32,
        directives_len: u32,
    ) -> CompileResult<()> {
        if directives_len == 0 {
            return Ok(());
        }
        let derive_dir_sym = self.interner.get_or_intern("derive");
        let directives = self.rir.get_directives(directives_start, directives_len);
        for d in directives {
            if d.name != derive_dir_sym {
                continue;
            }
            if d.args.len() != 1 {
                return Err(CompileError::new(
                    ErrorKind::DeriveNotADerive {
                        name: "<wrong arg count>".to_string(),
                        found: format!("{} arguments", d.args.len()),
                    },
                    d.span,
                ));
            }
            let derive_name = d.args[0];
            // ADR-0059: `@derive(Copy)` on an anonymous host is no-op for
            // method splicing; the posture bookkeeping flows through the
            // existing copy-directive path.
            if self.is_compiler_derive(derive_name) {
                continue;
            }
            let name_str = self.interner.resolve(&derive_name).to_string();
            if !self.derives.contains_key(&derive_name) {
                let found = if self.structs.contains_key(&derive_name) {
                    "struct"
                } else if self.enums.contains_key(&derive_name) {
                    "enum"
                } else if self.interfaces.contains_key(&derive_name) {
                    "interface"
                } else if self.functions.contains_key(&derive_name) {
                    "function"
                } else {
                    "unknown name"
                };
                return Err(CompileError::new(
                    ErrorKind::DeriveNotADerive {
                        name: name_str,
                        found: found.to_string(),
                    },
                    d.span,
                ));
            }
            self.splice_derive_methods_into_struct(derive_name, host_id, d.span)?;
        }
        Ok(())
    }

    /// Anonymous-enum mirror of `splice_anon_struct_derives`.
    pub(crate) fn splice_anon_enum_derives(
        &mut self,
        host_id: EnumId,
        directives_start: u32,
        directives_len: u32,
    ) -> CompileResult<()> {
        if directives_len == 0 {
            return Ok(());
        }
        let derive_dir_sym = self.interner.get_or_intern("derive");
        let directives = self.rir.get_directives(directives_start, directives_len);
        for d in directives {
            if d.name != derive_dir_sym {
                continue;
            }
            if d.args.len() != 1 {
                return Err(CompileError::new(
                    ErrorKind::DeriveNotADerive {
                        name: "<wrong arg count>".to_string(),
                        found: format!("{} arguments", d.args.len()),
                    },
                    d.span,
                ));
            }
            let derive_name = d.args[0];
            // ADR-0059: `@derive(Copy)` short-circuits — no methods to splice.
            if self.is_compiler_derive(derive_name) {
                continue;
            }
            let name_str = self.interner.resolve(&derive_name).to_string();
            if !self.derives.contains_key(&derive_name) {
                let found = if self.structs.contains_key(&derive_name) {
                    "struct"
                } else if self.enums.contains_key(&derive_name) {
                    "enum"
                } else if self.interfaces.contains_key(&derive_name) {
                    "interface"
                } else if self.functions.contains_key(&derive_name) {
                    "function"
                } else {
                    "unknown name"
                };
                return Err(CompileError::new(
                    ErrorKind::DeriveNotADerive {
                        name: name_str,
                        found: found.to_string(),
                    },
                    d.span,
                ));
            }
            self.splice_derive_methods_into_enum(derive_name, host_id, d.span)?;
        }
        Ok(())
    }

    /// Splice every method of `derive_name` into the struct identified by
    /// `host_id`. `Self` is bound to the host struct's `Type`.
    pub(crate) fn splice_derive_methods_into_struct(
        &mut self,
        derive_name: Spur,
        host_id: StructId,
        directive_span: Span,
    ) -> CompileResult<()> {
        // Snapshot the per-derive method list (we'll borrow `self` mutably
        // when calling `resolve_param_type` below).
        let methods: Vec<crate::sema::info::DeriveMethod> = match self.derives.get(&derive_name) {
            Some(info) => info.methods.clone(),
            None => return Ok(()),
        };
        let host_type = Type::new_struct(host_id);

        // ADR-0079: linear types must not pick up a Clone impl. The
        // prelude `derive Clone` synthesizes a fresh `Self` field-by-
        // field, which would silently duplicate a linear value. Catch
        // this at splice time so the diagnostic points at the
        // `@derive(Clone)` directive rather than at the synthesized
        // body's first @field_set.
        let derive_iface = self.interfaces.get(&derive_name).copied();
        if derive_iface.is_some()
            && derive_iface == self.lang_items.clone()
            && self.type_pool.struct_def(host_id).posture == Posture::Linear
        {
            let host_str = self.type_pool.struct_def(host_id).name.clone();
            return Err(CompileError::new(
                ErrorKind::LinearStructClone(host_str),
                directive_span,
            ));
        }

        // ADR-0076: bind `Self` to the host struct while resolving derived
        // method signatures.
        let saved_self = self.current_self.replace(host_type);

        let host_file_id = self.type_pool.struct_def(host_id).file_id;
        for dm in methods {
            let m = self.rir.get(dm.method_ref);
            let InstData::FnDecl {
                name: method_name,
                is_pub: method_is_pub,
                is_unchecked,
                params_start,
                params_len,
                return_type,
                body,
                has_self,
                receiver_mode,
                ..
            } = m.data
            else {
                continue;
            };
            let receiver = decode_receiver_mode(receiver_mode);
            let key = (host_id, method_name);
            if self.methods.contains_key(&key) {
                let derive_str = self.interner.resolve(&derive_name).to_string();
                let method_str = self.interner.resolve(&method_name).to_string();
                let host_str = self.type_pool.struct_def(host_id).name.clone();
                let prior_span = self.methods.get(&key).map(|info| info.span);
                let mut err = CompileError::new(
                    ErrorKind::DuplicateMethod {
                        type_name: format!(
                            "type `{}` (attached by `@derive({})`)",
                            host_str, derive_str
                        ),
                        method_name: method_str.clone(),
                    },
                    directive_span,
                )
                .with_label(
                    format!("`{}` declared inside `derive {}`", method_str, derive_str),
                    m.span,
                );
                if let Some(s) = prior_span {
                    err = err.with_label(format!("`{}` already attached here", method_str), s);
                }
                return Err(err);
            }

            let params = self.rir.get_params(params_start, params_len);
            let param_names: Vec<Spur> = params.iter().map(|p| p.name).collect();
            let param_comptime: Vec<bool> = params.iter().map(|p| p.is_comptime).collect();
            let mut param_types: Vec<Type> = Vec::with_capacity(params.len());
            let mut param_modes: Vec<gruel_rir::RirParamMode> = Vec::with_capacity(params.len());
            for p in &params {
                let (ty, mode) = self.resolve_param_type(p.ty, p.mode, m.span)?;
                param_types.push(ty);
                param_modes.push(mode);
            }
            let ret_type = self.resolve_type(return_type, m.span)?;
            let param_range =
                self.param_arena
                    .alloc(param_names, param_types, param_modes, param_comptime);

            // ADR-0073: derived methods are scoped to the host's module —
            // the host's file_id is the relevant target_file_id for any
            // visibility check at a call site.
            self.methods.insert(
                key,
                MethodInfo {
                    struct_type: host_type,
                    has_self,
                    receiver,
                    params: param_range,
                    return_type: ret_type,
                    body,
                    span: m.span,
                    is_unchecked,
                    is_generic: false,
                    return_type_sym: return_type,
                    is_pub: method_is_pub,
                    file_id: host_file_id,
                },
            );
        }
        self.current_self = saved_self;
        Ok(())
    }

    /// Splice every method of `derive_name` into the enum identified by
    /// `host_id`. `Self` is bound to the host enum's `Type`. Mirrors the
    /// struct case; structs and enums share the splicing logic (only the
    /// destination map differs).
    pub(crate) fn splice_derive_methods_into_enum(
        &mut self,
        derive_name: Spur,
        host_id: EnumId,
        directive_span: Span,
    ) -> CompileResult<()> {
        let methods: Vec<crate::sema::info::DeriveMethod> = match self.derives.get(&derive_name) {
            Some(info) => info.methods.clone(),
            None => return Ok(()),
        };
        let host_type = Type::new_enum(host_id);
        // ADR-0076: bind `Self` to the host enum while resolving derived
        // method signatures.
        let saved_self = self.current_self.replace(host_type);
        let host_file_id = self.type_pool.enum_def(host_id).file_id;

        for dm in methods {
            let m = self.rir.get(dm.method_ref);
            let InstData::FnDecl {
                name: method_name,
                is_pub: method_is_pub,
                is_unchecked,
                params_start,
                params_len,
                return_type,
                body,
                has_self,
                receiver_mode,
                ..
            } = m.data
            else {
                continue;
            };
            let receiver = decode_receiver_mode(receiver_mode);
            let key = (host_id, method_name);
            if self.enum_methods.contains_key(&key) {
                let derive_str = self.interner.resolve(&derive_name).to_string();
                let method_str = self.interner.resolve(&method_name).to_string();
                let prior_span = self.enum_methods.get(&key).map(|info| info.span);
                let mut err = CompileError::new(
                    ErrorKind::DuplicateMethod {
                        type_name: format!("enum (attached by `@derive({})`)", derive_str),
                        method_name: method_str.clone(),
                    },
                    directive_span,
                )
                .with_label(
                    format!("`{}` declared inside `derive {}`", method_str, derive_str),
                    m.span,
                );
                if let Some(s) = prior_span {
                    err = err.with_label(format!("`{}` already attached here", method_str), s);
                }
                return Err(err);
            }

            let params = self.rir.get_params(params_start, params_len);
            let param_names: Vec<Spur> = params.iter().map(|p| p.name).collect();
            let param_comptime: Vec<bool> = params.iter().map(|p| p.is_comptime).collect();
            let mut param_types: Vec<Type> = Vec::with_capacity(params.len());
            let mut param_modes: Vec<gruel_rir::RirParamMode> = Vec::with_capacity(params.len());
            for p in &params {
                let (ty, mode) = self.resolve_param_type(p.ty, p.mode, m.span)?;
                param_types.push(ty);
                param_modes.push(mode);
            }
            let ret_type = self.resolve_type(return_type, m.span)?;
            let param_range =
                self.param_arena
                    .alloc(param_names, param_types, param_modes, param_comptime);

            self.enum_methods.insert(
                key,
                MethodInfo {
                    struct_type: host_type,
                    has_self,
                    receiver,
                    params: param_range,
                    return_type: ret_type,
                    body,
                    span: m.span,
                    is_unchecked,
                    is_generic: false,
                    return_type_sym: return_type,
                    is_pub: method_is_pub,
                    file_id: host_file_id,
                },
            );
        }
        self.current_self = saved_self;
        Ok(())
    }

    /// Walk every named struct/enum declaration; for each `@derive(D)`
    /// directive, resolve `D` against `Sema::derives` and record a
    /// `DeriveBinding` for Phase 4. Errors if `D` doesn't name a `derive`
    /// item.
    pub(crate) fn resolve_derive_directives(&mut self) -> CompileResult<()> {
        use super::DeriveBinding;

        // Snapshot of struct/enum declarations carrying `@derive(...)`.
        struct RawAttach {
            host_name: Spur,
            host_is_enum: bool,
            host_span: Span,
            derive_names: Vec<(Spur, Span)>,
        }
        let derive_dir_sym = self.interner.get_or_intern("derive");
        let mut raw: Vec<RawAttach> = Vec::new();

        for (_, inst) in self.rir.iter() {
            // ADR-0079 Phase 1 routed directives through both
            // `StructDecl` and `EnumDecl`; collect from both so
            // `@derive(...)` works on enums too.
            let (directives_start, directives_len, name, host_is_enum) = match &inst.data {
                InstData::StructDecl {
                    directives_start,
                    directives_len,
                    name,
                    ..
                } => (*directives_start, *directives_len, *name, false),
                InstData::EnumDecl {
                    directives_start,
                    directives_len,
                    name,
                    ..
                } => (*directives_start, *directives_len, *name, true),
                _ => continue,
            };
            if directives_len == 0 {
                continue;
            }
            let directives = self.rir.get_directives(directives_start, directives_len);
            let mut attached = Vec::new();
            for d in &directives {
                if d.name == derive_dir_sym {
                    if d.args.len() != 1 {
                        return Err(CompileError::new(
                            ErrorKind::DeriveNotADerive {
                                name: "<wrong arg count>".to_string(),
                                found: format!("{} arguments", d.args.len()),
                            },
                            d.span,
                        ));
                    }
                    attached.push((d.args[0], d.span));
                }
            }
            if !attached.is_empty() {
                raw.push(RawAttach {
                    host_name: name,
                    host_is_enum,
                    host_span: inst.span,
                    derive_names: attached,
                });
            }
        }

        // Resolve each binding.
        for r in raw {
            for (derive_name, dir_span) in r.derive_names {
                // `@derive(Copy)` is compiler-recognized (ADR-0059): the
                // field-Copy validation already runs via the posture
                // bookkeeping, and there is no derive item to look up. Skip
                // the regular resolution path.
                if self.is_compiler_derive(derive_name) {
                    continue;
                }

                let name_str = self.interner.resolve(&derive_name).to_string();

                // Resolution order: a `derive` item, else categorize what
                // we actually found for a clearer diagnostic.
                if !self.derives.contains_key(&derive_name) {
                    let found = if self.structs.contains_key(&derive_name) {
                        "struct"
                    } else if self.enums.contains_key(&derive_name) {
                        "enum"
                    } else if self.interfaces.contains_key(&derive_name) {
                        "interface"
                    } else if self.functions.contains_key(&derive_name) {
                        "function"
                    } else {
                        "unknown name"
                    };
                    return Err(CompileError::new(
                        ErrorKind::DeriveNotADerive {
                            name: name_str,
                            found: found.to_string(),
                        },
                        dir_span,
                    ));
                }

                self.derive_bindings.push(DeriveBinding {
                    host_name: r.host_name,
                    host_is_enum: r.host_is_enum,
                    derive_name,
                    host_span: r.host_span,
                    directive_span: dir_span,
                });
            }
        }

        Ok(())
    }

    /// ADR-0059 / ADR-0079: a name was previously recognized as a
    /// compiler-handled derive (`Copy` was the only such name).
    /// ADR-0080 retired `Copy` from the interface registry, so this
    /// hook always returns `false` and `@derive(...)` resolution
    /// flows entirely through the standard derive-resolution path —
    /// `@derive(Copy)` falls through the existing "unknown interface"
    /// diagnostic, exactly as the ADR specified.
    fn is_compiler_derive(&self, _name: Spur) -> bool {
        false
    }

    /// ADR-0058 phases 1 + 2: gate `derive` items behind the
    /// `comptime_derives` preview feature, register each into
    /// `Sema::derives` for later expansion, and reject ill-formed bodies
    /// (duplicate names, name collisions with structs/enums/interfaces,
    /// duplicate methods within a single derive, and direct `self.field`
    /// projection — the host type's structure isn't known at
    /// derive-definition time).
    pub(crate) fn validate_derive_decls(&mut self) -> CompileResult<()> {
        use super::DeriveInfo;
        use crate::sema::info::DeriveMethod;

        // Snapshot: copy out enough RIR data so we can mutate `self.derives`
        // and emit diagnostics without holding shared borrows on `self.rir`.
        struct RawDerive {
            name: Spur,
            decl_ref: gruel_rir::InstRef,
            span: Span,
            methods_start: u32,
            methods_len: u32,
        }
        let mut raw: Vec<RawDerive> = Vec::new();
        for (inst_ref, inst) in self.rir.iter() {
            if let InstData::DeriveDecl {
                name,
                methods_start,
                methods_len,
            } = &inst.data
            {
                raw.push(RawDerive {
                    name: *name,
                    decl_ref: inst_ref,
                    span: inst.span,
                    methods_start: *methods_start,
                    methods_len: *methods_len,
                });
            }
        }

        for d in raw {
            let name_str = self.interner.resolve(&d.name).to_string();

            // ADR-0079: a derive may share its name with an interface so the
            // prelude can ship `derive Clone {...}` alongside
            // `interface Clone {...}` — the derive provides an implementation
            // for that interface. Other collisions (struct, enum, another
            // derive) remain rejected.
            if self.derives.contains_key(&d.name)
                || self.structs.contains_key(&d.name)
                || self.enums.contains_key(&d.name)
            {
                return Err(CompileError::new(
                    ErrorKind::DuplicateTypeDefinition {
                        type_name: format!("derive `{}`", name_str),
                    },
                    d.span,
                ));
            }

            let method_refs = self.rir.get_inst_refs(d.methods_start, d.methods_len);
            let mut seen: HashSet<Spur> = HashSet::default();
            let mut methods: Vec<DeriveMethod> = Vec::with_capacity(method_refs.len());
            for method_ref in method_refs {
                let m = self.rir.get(method_ref);
                let InstData::FnDecl {
                    name: method_name,
                    has_self,
                    ..
                } = &m.data
                else {
                    // The grammar only admits method declarations inside a
                    // derive body, but if RIR ever produces something else
                    // we surface a clear diagnostic instead of panicking.
                    return Err(CompileError::new(
                        ErrorKind::InternalError(format!(
                            "non-method instruction inside `derive {}` body",
                            name_str
                        )),
                        m.span,
                    ));
                };

                if !seen.insert(*method_name) {
                    return Err(CompileError::new(
                        ErrorKind::DuplicateMethod {
                            type_name: format!("derive `{}`", name_str),
                            method_name: self.interner.resolve(method_name).to_string(),
                        },
                        m.span,
                    ));
                }

                self.reject_direct_self_projection(*method_name, &name_str, method_ref)?;

                methods.push(DeriveMethod {
                    name: *method_name,
                    has_self: *has_self,
                    method_ref,
                    span: m.span,
                });
            }

            self.derives.insert(
                d.name,
                DeriveInfo {
                    name: d.name,
                    decl_ref: d.decl_ref,
                    span: d.span,
                    methods,
                },
            );
        }

        Ok(())
    }

    /// Walk the RIR range `[body_start, decl)` for the method whose `FnDecl`
    /// is at `method_ref`, and reject any `FieldGet { base: VarRef "self" }`.
    /// The host's structure isn't known at derive-definition time, so direct
    /// projection (`self.x`) is illegal — users must go through
    /// `@field(self, "x")` (ADR-0058).
    fn reject_direct_self_projection(
        &self,
        method_name: Spur,
        derive_name: &str,
        method_ref: gruel_rir::InstRef,
    ) -> CompileResult<()> {
        let self_sym = match self.interner.get("self") {
            Some(s) => s,
            // No `self` symbol exists yet, so no method can reference it.
            None => return Ok(()),
        };

        // Find this method's function span so we can iterate just its body.
        let span = match self
            .rir
            .function_spans()
            .iter()
            .find(|s| s.decl == method_ref)
        {
            Some(s) => s,
            None => return Ok(()),
        };

        let view = self.rir.function_view(span);
        for (_, inst) in view.iter() {
            if let InstData::FieldGet { base, .. } = &inst.data {
                let base_inst = self.rir.get(*base);
                if let InstData::VarRef { name } = &base_inst.data
                    && *name == self_sym
                {
                    return Err(CompileError::new(
                        ErrorKind::DeriveDirectFieldAccess {
                            derive_name: derive_name.to_string(),
                            method_name: self.interner.resolve(&method_name).to_string(),
                        },
                        inst.span,
                    ));
                }
            }
        }
        Ok(())
    }

    /// Resolve enum variant field types. Must run after all type names are registered
    /// so that field types can reference other enums/structs.
    pub(crate) fn resolve_enum_variant_fields(&mut self) -> CompileResult<()> {
        for (_, inst) in self.rir.iter() {
            if let InstData::EnumDecl {
                name,
                variants_start,
                variants_len,
                ..
            } = &inst.data
            {
                let enum_id = match self.enums.get(name) {
                    Some(id) => *id,
                    None => continue, // not registered (shouldn't happen)
                };

                let raw_variants = self
                    .rir
                    .get_enum_variant_decls(*variants_start, *variants_len);
                let has_data = raw_variants.iter().any(|(_, fields, _)| !fields.is_empty());
                if !has_data {
                    continue; // unit-only enum, no field types to resolve
                }

                let mut resolved_variants = Vec::with_capacity(raw_variants.len());
                for (vname, field_type_spurs, field_name_spurs) in &raw_variants {
                    let mut resolved_fields = Vec::with_capacity(field_type_spurs.len());
                    for field_ty_spur in field_type_spurs {
                        let field_ty = self.resolve_type(*field_ty_spur, inst.span)?;
                        resolved_fields.push(field_ty);
                    }
                    let field_names: Vec<String> = field_name_spurs
                        .iter()
                        .map(|n| self.interner.resolve(n).to_string())
                        .collect();
                    resolved_variants.push(EnumVariantDef {
                        name: self.interner.resolve(vname).to_string(),
                        fields: resolved_fields,
                        field_names,
                    });
                }

                let mut enum_def = self.type_pool.enum_def(enum_id);
                enum_def.variants = resolved_variants;
                self.type_pool.update_enum_def(enum_id, enum_def);
            }
        }
        Ok(())
    }

    /// ADR-0080 Phase 3: posture-consistency walker.
    ///
    /// Runs after `resolve_struct_fields` and `resolve_enum_variant_fields`
    /// have populated every field/variant `Type`, but before the rest of
    /// `resolve_remaining_declarations`. For every named struct or enum
    /// declaration, it classifies each member's posture (Copy / Affine /
    /// Linear) and folds the result into the propagated posture, then
    /// compares against the declared posture from the keyword:
    ///
    /// | Declared    | Rule                                   |
    /// |-------------|----------------------------------------|
    /// | `copy`      | every member must be Copy              |
    /// | (unmarked)  | no member may be Linear                |
    /// | `linear`    | (no constraint — linear holds anything)|
    ///
    /// On mismatch the error span is the host declaration's span and the
    /// message names the offending member's type and posture (richer
    /// per-field spans land when struct/enum field positions become
    /// addressable from `StructDef` / `EnumDef`).
    ///
    /// The walker is one function rather than a struct-validator + enum-
    /// validator pair because the only difference between the two cases is
    /// how members are enumerated; the posture-folding logic is identical.
    ///
    /// ADR-0084: in addition to computing posture, this pass also computes
    /// the structural minimum thread-safety classification over members
    /// and applies any `@mark(unsend)` / `@mark(checked_send)` /
    /// `@mark(checked_sync)` override recorded in
    /// `mark_thread_safety_decls`. The function was renamed from
    /// `validate_posture_consistency` when the thread-safety axis was
    /// added.
    pub(crate) fn validate_consistency(&mut self) -> CompileResult<()> {
        // ADR-0083 Phase 1: instead of just validating declared posture
        // against members, we run *uniform structural inference* on every
        // named struct/enum. The result reconciles with whatever the user
        // declared via the `copy`/`linear` keyword (ADR-0080) or
        // `@mark(...)` directive (ADR-0083):
        //
        // - declared Linear (or `@mark(linear)`) → final is Linear (no
        //   member constraint).
        // - declared Copy (or `@mark(copy)`) → every member must be Copy;
        //   final is Copy.
        // - declared Affine via `@mark(affine)` → no member may be
        //   Linear; final is Affine (suppresses Copy inference).
        // - no declaration → final posture is the inferred posture
        //   (NEW: previously named types were Affine by default; now
        //   structs/enums of all-Copy members infer Copy).
        //
        // ADR-0080 carve-out: types with `fn __drop(self)` are never Copy
        // (Copy ⊥ Drop). We pre-scan RIR for both inline `fn __drop` methods
        // and top-level `drop fn TypeName(self)` declarations and downgrade
        // Copy → Affine when a destructor is present.
        //
        // Member-postures are classified via `classify_posture`, which
        // already handles arrays/tuples/Vec/Option/Result transparently.
        let types_with_drop = self.collect_types_with_drop();
        for (_, inst) in self.rir.iter() {
            match &inst.data {
                InstData::StructDecl {
                    name,
                    methods_start,
                    methods_len,
                    ..
                } => {
                    let Some(&struct_id) = self.structs.get(name) else {
                        continue;
                    };
                    let def = self.type_pool.struct_def(struct_id);
                    let declared_affine = self.mark_affine_decls.contains(name);
                    let declared = match def.posture {
                        Posture::Linear => DeclaredPosture::Linear,
                        Posture::Copy => DeclaredPosture::Copy,
                        Posture::Affine if declared_affine => DeclaredPosture::Affine,
                        Posture::Affine => DeclaredPosture::Unmarked,
                    };
                    let host_name = def.name.clone();
                    let mut any_linear = false;
                    let mut all_copy = true;
                    for field in &def.fields {
                        let posture = self.classify_posture(field.ty);
                        match posture {
                            MemberPosture::Linear => any_linear = true,
                            MemberPosture::Affine => all_copy = false,
                            MemberPosture::Copy => {}
                        }
                        if let Some(err) = check_posture_against_declared(
                            "struct",
                            host_name.as_str(),
                            declared,
                            "field",
                            &field.name,
                            self.format_type_name(field.ty).as_str(),
                            posture,
                            inst.span,
                        ) {
                            return Err(err);
                        }
                    }
                    let has_drop = self.has_inline_drop_method(*methods_start, *methods_len)
                        || types_with_drop.contains(name);
                    let inferred = if any_linear {
                        MemberPosture::Linear
                    } else if all_copy && !has_drop {
                        MemberPosture::Copy
                    } else {
                        MemberPosture::Affine
                    };
                    // ADR-0084: structural minimum over fields. Empty
                    // composites fold to `Sync`, the identity element.
                    let inferred_thread_safety = self
                        .type_pool
                        .struct_def(struct_id)
                        .fields
                        .iter()
                        .map(|f| self.type_pool.is_thread_safety_type(f.ty))
                        .min()
                        .unwrap_or(ThreadSafety::Sync);
                    let thread_safety_override = self.mark_thread_safety_decls.get(name).copied();
                    self.apply_inferred_struct_posture(struct_id, declared, inferred);
                    self.apply_thread_safety_struct(
                        struct_id,
                        inferred_thread_safety,
                        thread_safety_override,
                    );
                }
                InstData::EnumDecl {
                    name,
                    methods_start,
                    methods_len,
                    ..
                } => {
                    let Some(&enum_id) = self.enums.get(name) else {
                        continue;
                    };
                    let def = self.type_pool.enum_def(enum_id);
                    let declared_affine = self.mark_affine_decls.contains(name);
                    let declared = match def.posture {
                        Posture::Linear => DeclaredPosture::Linear,
                        Posture::Copy => DeclaredPosture::Copy,
                        Posture::Affine if declared_affine => DeclaredPosture::Affine,
                        Posture::Affine => DeclaredPosture::Unmarked,
                    };
                    let host_name = def.name.clone();
                    let mut any_linear = false;
                    let mut all_copy = true;
                    for variant in &def.variants {
                        for (i, field_ty) in variant.fields.iter().enumerate() {
                            let member_name = if let Some(name) = variant.field_names.get(i) {
                                format!("{}::{}.{}", host_name, variant.name, name)
                            } else {
                                format!("{}::{}.{}", host_name, variant.name, i)
                            };
                            let posture = self.classify_posture(*field_ty);
                            match posture {
                                MemberPosture::Linear => any_linear = true,
                                MemberPosture::Affine => all_copy = false,
                                MemberPosture::Copy => {}
                            }
                            if let Some(err) = check_posture_against_declared(
                                "enum",
                                host_name.as_str(),
                                declared,
                                "variant field",
                                &member_name,
                                self.format_type_name(*field_ty).as_str(),
                                posture,
                                inst.span,
                            ) {
                                return Err(err);
                            }
                        }
                    }
                    let has_drop = self.has_inline_drop_method(*methods_start, *methods_len)
                        || types_with_drop.contains(name);
                    let inferred = if any_linear {
                        MemberPosture::Linear
                    } else if all_copy && !has_drop {
                        MemberPosture::Copy
                    } else {
                        MemberPosture::Affine
                    };
                    // ADR-0084: structural minimum across every variant
                    // payload field. Mirrors the struct branch above.
                    let inferred_thread_safety = self
                        .type_pool
                        .enum_def(enum_id)
                        .variants
                        .iter()
                        .flat_map(|v| v.fields.iter().copied())
                        .map(|f| self.type_pool.is_thread_safety_type(f))
                        .min()
                        .unwrap_or(ThreadSafety::Sync);
                    let thread_safety_override = self.mark_thread_safety_decls.get(name).copied();
                    self.apply_inferred_enum_posture(enum_id, declared, inferred);
                    self.apply_thread_safety_enum(
                        enum_id,
                        inferred_thread_safety,
                        thread_safety_override,
                    );
                }
                _ => {}
            }
        }
        Ok(())
    }

    /// ADR-0083 (revised): destructors are `fn __drop(self)` methods
    /// declared inside the struct body. The retired top-level
    /// `drop fn TypeName(self)` form had its own collection pass; with
    /// it gone, only `has_inline_drop_method` remains.
    fn collect_types_with_drop(&self) -> HashSet<Spur> {
        // No top-level drop fns; inline `fn __drop(self)` is detected via
        // `has_inline_drop_method` at the per-decl site.
        HashSet::default()
    }

    /// ADR-0080 / ADR-0083: detect whether a struct/enum's inline method
    /// list contains a `fn __drop(self)` declaration.
    fn has_inline_drop_method(&self, methods_start: u32, methods_len: u32) -> bool {
        if methods_len == 0 {
            return false;
        }
        let drop_name = self.interner.get("__drop");
        let Some(drop_name) = drop_name else {
            return false;
        };
        let method_refs = self.rir.get_inst_refs(methods_start, methods_len);
        for method_ref in method_refs {
            let method_inst = self.rir.get(method_ref);
            if let InstData::FnDecl { name, has_self, .. } = &method_inst.data
                && *name == drop_name
                && *has_self
            {
                return true;
            }
        }
        false
    }

    /// ADR-0083 Phase 1: write the final posture into the struct's
    /// `posture` field. If the user declared the posture (`copy struct`
    /// / `linear struct` / `@mark(...)`), the field is already set in
    /// `register_type_names`; we only need to fill it in for unmarked
    /// types from the inferred posture.
    fn apply_inferred_struct_posture(
        &mut self,
        struct_id: StructId,
        declared: DeclaredPosture,
        inferred: MemberPosture,
    ) {
        if declared != DeclaredPosture::Unmarked {
            return;
        }
        let mut def = self.type_pool.struct_def(struct_id);
        def.posture = match inferred {
            MemberPosture::Copy => Posture::Copy,
            MemberPosture::Affine => Posture::Affine,
            MemberPosture::Linear => Posture::Linear,
        };
        self.type_pool.update_struct_def(struct_id, def);
    }

    fn apply_inferred_enum_posture(
        &mut self,
        enum_id: EnumId,
        declared: DeclaredPosture,
        inferred: MemberPosture,
    ) {
        if declared != DeclaredPosture::Unmarked {
            return;
        }
        let mut def = self.type_pool.enum_def(enum_id);
        def.posture = match inferred {
            MemberPosture::Copy => Posture::Copy,
            MemberPosture::Affine => Posture::Affine,
            MemberPosture::Linear => Posture::Linear,
        };
        self.type_pool.update_enum_def(enum_id, def);
    }

    /// ADR-0084: write the final thread-safety classification on the
    /// struct's def. The user override (if any) wins, even when it
    /// contradicts the structurally-inferred value — that's the whole
    /// point of `@mark(checked_send)` / `@mark(checked_sync)`. The
    /// `unsend` marker is also accepted regardless of inference (always
    /// safe to restrict).
    fn apply_thread_safety_struct(
        &self,
        struct_id: StructId,
        inferred: ThreadSafety,
        override_: Option<ThreadSafety>,
    ) {
        let mut def = self.type_pool.struct_def(struct_id);
        def.thread_safety = override_.unwrap_or(inferred);
        self.type_pool.update_struct_def(struct_id, def);
    }

    fn apply_thread_safety_enum(
        &self,
        enum_id: EnumId,
        inferred: ThreadSafety,
        override_: Option<ThreadSafety>,
    ) {
        let mut def = self.type_pool.enum_def(enum_id);
        def.thread_safety = override_.unwrap_or(inferred);
        self.type_pool.update_enum_def(enum_id, def);
    }

    /// Classify a type's ownership posture (ADR-0080).
    fn classify_posture(&self, ty: crate::types::Type) -> MemberPosture {
        if self.is_type_linear(ty) {
            MemberPosture::Linear
        } else if self.is_type_copy(ty) {
            MemberPosture::Copy
        } else {
            MemberPosture::Affine
        }
    }

    // ADR-0080 helper end.

    /// Resolve struct field types. Must run before @derive(Copy) validation.
    pub(crate) fn resolve_struct_fields(&mut self) -> CompileResult<()> {
        for (_, inst) in self.rir.iter() {
            if let InstData::StructDecl {
                name,
                fields_start,
                fields_len,
                ..
            } = &inst.data
            {
                let name_str = self.interner.resolve(name).to_string();
                // Verify the struct exists in our lookup table
                if !self.structs.contains_key(name) {
                    return Err(CompileError::new(
                        ErrorKind::InternalError(
                            ice!(
                                "struct not found in struct map",
                                phase: "sema/declarations",
                                details: {
                                    "struct_name" => name_str.to_string()
                                }
                            )
                            .to_string(),
                        ),
                        inst.span,
                    ));
                }

                // Get the struct ID from the lookup table
                let struct_id = *self.structs.get(name).ok_or_else(|| {
                    CompileError::new(
                        ErrorKind::InternalError(
                            ice!(
                                "struct not found in structs map",
                                phase: "sema/declarations",
                                details: {
                                    "struct_name" => name_str.to_string()
                                }
                            )
                            .to_string(),
                        ),
                        inst.span,
                    )
                })?;

                let struct_name = name_str.clone();
                let fields = self
                    .rir
                    .get_field_decls_with_vis(*fields_start, *fields_len);

                // Check for duplicate field names
                let mut seen_fields: HashSet<Spur> = HashSet::default();
                for (field_name, _, _) in &fields {
                    if !seen_fields.insert(*field_name) {
                        let field_name_str = self.interner.resolve(field_name).to_string();
                        return Err(CompileError::new(
                            ErrorKind::DuplicateField {
                                struct_name,
                                field_name: field_name_str,
                            },
                            inst.span,
                        ));
                    }
                }

                // Resolve field types
                let mut resolved_fields = Vec::new();
                for (field_name, field_type, is_pub) in &fields {
                    let field_ty = self.resolve_type(*field_type, inst.span)?;
                    resolved_fields.push(StructField {
                        name: self.interner.resolve(field_name).to_string(),
                        ty: field_ty,

                        is_pub: *is_pub,
                    });
                }

                // Update the struct definition in the pool with resolved fields
                let mut struct_def = self.type_pool.struct_def(struct_id);
                // ADR-0085: validate `@mark(c)` struct fields recursively.
                // Any non-C field on a C-layout struct is rejected.
                if struct_def.is_c_layout {
                    for f in &resolved_fields {
                        self.validate_ffi_type(
                            f.ty,
                            &format!(
                                "as the type of field `{}` on `@mark(c) struct {}`",
                                f.name, struct_def.name
                            ),
                            inst.span,
                        )?;
                    }
                }
                struct_def.fields = resolved_fields;
                self.type_pool.update_struct_def(struct_id, struct_def);
            }
        }
        Ok(())
    }

    /// Resolve @derive(Copy) validation, destructors, functions, and methods.
    pub(crate) fn resolve_remaining_declarations(&mut self) -> CompileResult<()> {
        // Collect all method InstRefs that should NOT be processed as
        // top-level functions:
        //
        // - Anonymous struct/enum methods are registered later during
        //   comptime evaluation with proper Self resolution.
        // - `derive` body methods (ADR-0058) are spliced into a host type
        //   at expansion time.
        // - Named struct/enum methods (including associated functions like
        //   `fn new() -> Self`) are collected via `collect_struct_methods` /
        //   `collect_enum_methods` with `current_self` set per ADR-0076.
        let mut anon_type_method_refs = rustc_hash::FxHashSet::default();
        for (_, inst) in self.rir.iter() {
            let (methods_start, methods_len) = match &inst.data {
                InstData::AnonStructType {
                    methods_start,
                    methods_len,
                    ..
                } => (*methods_start, *methods_len),
                InstData::AnonEnumType {
                    methods_start,
                    methods_len,
                    ..
                } => (*methods_start, *methods_len),
                InstData::DeriveDecl {
                    methods_start,
                    methods_len,
                    ..
                } => (*methods_start, *methods_len),
                InstData::StructDecl {
                    methods_start,
                    methods_len,
                    ..
                } => (*methods_start, *methods_len),
                InstData::EnumDecl {
                    methods_start,
                    methods_len,
                    ..
                } => (*methods_start, *methods_len),
                _ => continue,
            };
            let method_refs = self.rir.get_inst_refs(methods_start, methods_len);
            for method_ref in method_refs {
                anon_type_method_refs.insert(method_ref);
            }
        }

        // First pass: collect all declarations and validate @derive(Copy) structs
        for (inst_ref, inst) in self.rir.iter() {
            match &inst.data {
                InstData::StructDecl {
                    directives_start,
                    directives_len,
                    name,
                    methods_start,
                    methods_len,
                    ..
                } => {
                    // ADR-0079: `validate_copy_struct` and
                    // `validate_clone_struct` are both retired. The
                    // prelude `derive Copy` / `derive Clone` bodies
                    // express the field-Copy / field-Clone
                    // invariants in Gruel via
                    // `comptime_unroll for f in @type_info(Self).fields`
                    // + `comptime if (!@implements(f.field_type, …))`
                    // + `@compile_error`. Linearity is enforced by
                    // the structural Copy/Clone conformance checks.
                    let _ = (*directives_start, *directives_len);
                    // Collect methods defined inline in the struct
                    self.collect_struct_methods(*name, *methods_start, *methods_len, inst.span)?;
                }

                InstData::EnumDecl {
                    name,
                    methods_start,
                    methods_len,
                    ..
                } => {
                    // Collect methods defined inline in the enum (ADR-0053).
                    self.collect_enum_methods(*name, *methods_start, *methods_len, inst.span)?;
                }

                InstData::FnDecl {
                    directives_start,
                    directives_len,
                    is_pub,
                    is_unchecked,
                    name,
                    params_start,
                    params_len,
                    return_type,
                    body,
                    has_self,
                    ..
                } => {
                    // Skip methods (has_self = true) - these are handled elsewhere:
                    // - Named struct methods are collected via ImplDecl
                    if *has_self {
                        continue;
                    }

                    // Skip ALL methods from anonymous types (structs and enums)
                    // These are registered during comptime evaluation with proper Self type context
                    if anon_type_method_refs.contains(&inst_ref) {
                        continue;
                    }
                    self.collect_function_signature(
                        *name,
                        (*params_start, *params_len),
                        *return_type,
                        *body,
                        inst.span,
                        FnFlags {
                            is_pub: *is_pub,
                            is_unchecked: *is_unchecked,
                            directives_start: *directives_start,
                            directives_len: *directives_len,
                        },
                    )?;
                }

                InstData::ConstDecl {
                    is_pub, name, init, ..
                } => {
                    self.collect_const_declaration(*name, *is_pub, *init, inst.span)?;
                }

                _ => {}
            }
        }

        // ADR-0085: register every fn declared inside a `link_extern("…") { … }`
        // block. Gated behind the `c_ffi` preview feature.
        self.collect_extern_fn_signatures()?;

        Ok(())
    }

    /// ADR-0085: validate that a `Type` is allowed at the FFI boundary.
    ///
    /// Allowed: numeric primitives, `bool`, `()`, `Ptr(T)`, `MutPtr(T)`,
    /// and `@mark(c) struct T`. Enums are rejected entirely in v1 — see
    /// the deferred enum-FFI follow-up. `&T` / `&mut T`, slices, owned
    /// containers, and non-C-layout aggregates are rejected here.
    fn validate_ffi_type(&self, ty: Type, position: &str, span: Span) -> CompileResult<()> {
        // Scalar primitives and unit pass.
        if matches!(
            ty,
            Type::I8
                | Type::I16
                | Type::I32
                | Type::I64
                | Type::ISIZE
                | Type::U8
                | Type::U16
                | Type::U32
                | Type::U64
                | Type::USIZE
                | Type::F32
                | Type::F64
                | Type::BOOL
                | Type::UNIT
                // ADR-0086 C named arithmetic primitive types.
                | Type::C_SCHAR
                | Type::C_SHORT
                | Type::C_INT
                | Type::C_LONG
                | Type::C_LONGLONG
                | Type::C_UCHAR
                | Type::C_USHORT
                | Type::C_UINT
                | Type::C_ULONG
                | Type::C_ULONGLONG
                | Type::C_FLOAT
                | Type::C_DOUBLE
        ) {
            return Ok(());
        }

        // Raw pointers (ADR-0061) cross the boundary as `const T*`/`T*`.
        // ADR-0086: `Ptr(c_void)` / `MutPtr(c_void)` are also permitted —
        // c_void is allowed inside pointer types but rejected as a value.
        if ty.is_ptr_const() || ty.is_ptr_mut() {
            return Ok(());
        }

        // `@mark(c) struct T` is allowed by value.
        if let Some(struct_id) = ty.as_struct() {
            let def = self.type_pool.struct_def(struct_id);
            if def.is_c_layout {
                return Ok(());
            }
            return Err(CompileError::new(
                ErrorKind::CFfi(format!(
                    "type `{}` cannot cross the FFI boundary {}: \
                     non-`@mark(c)` struct (or container) types are not \
                     C-ABI compatible",
                    def.name, position
                )),
                span,
            ));
        }

        // ADR-0086: `@mark(c) enum E` is allowed by value. Field-less
        // enums lower to a bare `c_int`; data-carrying enums use the
        // C tagged-union layout `{ tag: c_int; payload: union<…> }`.
        // Variant payload fields must themselves be C-FFI types.
        // Non-`@mark(c)` enums stay rejected.
        if let Some(enum_id) = ty.as_enum() {
            let def = self.type_pool.enum_def(enum_id);
            if def.is_c_layout {
                let enum_name = def.name.clone();
                let variants = def.variants.clone();
                // Recursively validate each variant payload field — it
                // must itself be an FFI-compatible type. Mirrors the
                // recursion the @mark(c) struct path uses.
                for variant in &variants {
                    for &field_ty in &variant.fields {
                        if let Err(mut e) = self.validate_ffi_type(field_ty, position, span) {
                            // Wrap the inner diagnostic so the user
                            // sees which enum variant payload field
                            // is at fault.
                            if let ErrorKind::CFfi(inner) = &e.kind {
                                e.kind = ErrorKind::CFfi(format!(
                                    "variant `{}` of `@mark(c) enum {}` payload field has \
                                     a non-FFI type: {}",
                                    variant.name, enum_name, inner
                                ));
                            }
                            return Err(e);
                        }
                    }
                }
                return Ok(());
            }
            return Err(CompileError::new(
                ErrorKind::CFfi(format!(
                    "type `{}` cannot cross the FFI boundary {}: \
                     non-`@mark(c)` enum types are not C-ABI compatible",
                    def.name, position
                )),
                span,
            ));
        }

        // Everything else is rejected.
        Err(CompileError::new(
            ErrorKind::CFfi(format!(
                "this type cannot cross the FFI boundary {}: \
                 only numeric primitives, `bool`, `()`, `Ptr(T)`, `MutPtr(T)`, \
                 and `@mark(c) struct` types are permitted",
                position
            )),
            span,
        ))
    }

    /// ADR-0085: register every C extern fn declared in `link_extern` blocks.
    ///
    /// Each entry on `Rir::extern_fns()` becomes a `FunctionInfo` with
    /// `is_extern = true`, `is_c_abi = true`, and `link_library = Some(...)`.
    /// The body slot is filled with a sentinel `InstRef`; codegen sees the
    /// `is_extern` flag and emits a declaration only.
    fn collect_extern_fn_signatures(&mut self) -> CompileResult<()> {
        let extern_fns: Vec<_> = self.rir.extern_fns().to_vec();
        let empty_blocks: Vec<_> = self.rir.empty_link_extern_blocks().to_vec();
        if extern_fns.is_empty() && empty_blocks.is_empty() {
            return Ok(());
        }
        // ADR-0085: any `link_extern` block fires the c_ffi preview gate.
        // Pick the first block-span we see for the diagnostic anchor.
        // ADR-0085: validate library names — non-empty per spec 10.2:5.
        // (C FFI is stable as of ADR-0085 Phase 5; no preview gate.)
        for ext in &extern_fns {
            if self.interner.resolve(&ext.library).is_empty() {
                return Err(CompileError::new(
                    ErrorKind::CFfi(
                        "`link_extern(\"…\")` library name must not be empty".to_string(),
                    ),
                    ext.block_span,
                ));
            }
        }
        for (lib, _link_mode, block_span) in &empty_blocks {
            if self.interner.resolve(lib).is_empty() {
                return Err(CompileError::new(
                    ErrorKind::CFfi(
                        "`link_extern(\"…\")` library name must not be empty".to_string(),
                    ),
                    *block_span,
                ));
            }
        }

        // ADR-0086: a given library cannot be declared with both
        // dynamic (`link_extern`) and static (`static_link_extern`)
        // linkage across the same compilation unit. Fire the
        // c_ffi_extras preview gate on any `static_link_extern` block
        // (the dynamic path is stable from ADR-0085).
        use gruel_rir::inst::RirLinkMode;
        use rustc_hash::FxHashMap;
        let mut linkage_by_lib: FxHashMap<Spur, (RirLinkMode, Span)> = FxHashMap::default();
        for ext in &extern_fns {
            let entry = linkage_by_lib
                .entry(ext.library)
                .or_insert((ext.link_mode, ext.block_span));
            if entry.0 != ext.link_mode {
                let lib_name = self.interner.resolve(&ext.library).to_string();
                return Err(CompileError::new(
                    ErrorKind::CFfi(format!(
                        "library `{}` is declared with both `link_extern` (dynamic) and \
                         `static_link_extern` (static) linkage; a library must use a \
                         single linkage mode across the compilation unit",
                        lib_name
                    )),
                    ext.block_span,
                ));
            }
        }
        for (lib, link_mode, block_span) in &empty_blocks {
            let entry = linkage_by_lib
                .entry(*lib)
                .or_insert((*link_mode, *block_span));
            if entry.0 != *link_mode {
                let lib_name = self.interner.resolve(lib).to_string();
                return Err(CompileError::new(
                    ErrorKind::CFfi(format!(
                        "library `{}` is declared with both `link_extern` (dynamic) and \
                         `static_link_extern` (static) linkage; a library must use a \
                         single linkage mode across the compilation unit",
                        lib_name
                    )),
                    *block_span,
                ));
            }
        }

        for ext in &extern_fns {
            let params = self.rir.get_params(ext.params_start, ext.params_len);
            let param_names: Vec<Spur> = params.iter().map(|p| p.name).collect();
            let mut param_types = Vec::with_capacity(params.len());
            let mut param_modes = Vec::with_capacity(params.len());
            let mut param_comptime = Vec::with_capacity(params.len());
            for p in &params {
                if p.is_comptime {
                    return Err(CompileError::new(
                        ErrorKind::CFfi(
                            "extern fns inside `link_extern` must not declare \
                             comptime parameters"
                                .to_string(),
                        ),
                        ext.span,
                    ));
                }
                let (ty, mode) = self.resolve_param_type(p.ty, p.mode, ext.span)?;
                self.validate_ffi_type(ty, "as a parameter type", ext.span)?;
                param_types.push(ty);
                param_modes.push(mode);
                param_comptime.push(false);
            }
            let ret_type = self.resolve_type(ext.return_type, ext.span)?;
            self.validate_ffi_type(ret_type, "as a return type", ext.span)?;
            let params_range =
                self.param_arena
                    .alloc(param_names, param_types, param_modes, param_comptime);

            // ADR-0085: process directives on the extern fn. Today the only
            // supported one is `@link_name("…")`.
            // ADR-0088: extern fns also accept `@mark(unchecked)` and,
            // under the `unchecked_fn_extensions` preview gate, are
            // required to carry it. The gate fires below after the
            // directive scan completes.
            let directives = self
                .rir
                .get_directives(ext.directives_start, ext.directives_len);
            let mut link_name_override: Option<Spur> = None;
            let mut has_unchecked_mark = false;
            for d in directives.iter() {
                let dir_name = self.interner.resolve(&d.name).to_string();
                match dir_name.as_str() {
                    "link_name" => {
                        if d.args.len() != 1 {
                            return Err(CompileError::new(
                                ErrorKind::CFfi(
                                    "`@link_name(\"…\")` takes exactly one string argument"
                                        .to_string(),
                                ),
                                d.span,
                            ));
                        }
                        link_name_override = Some(d.args[0]);
                    }
                    "mark" => {
                        // ADR-0085: redundant `@mark(c)` inside a
                        // `link_extern` block is permitted. ADR-0088:
                        // `@mark(unchecked)` is the required form for
                        // every extern fn (gated by preview). Other
                        // marker names are rejected.
                        for arg in &d.args {
                            let name = self.interner.resolve(arg);
                            if name == "c" {
                                // accepted, no-op
                            } else if name == "unchecked" {
                                has_unchecked_mark = true;
                            } else {
                                return Err(CompileError::new(
                                    ErrorKind::CFfi(format!(
                                        "marker `{}` is not valid on extern fns inside `link_extern`",
                                        name
                                    )),
                                    d.span,
                                ));
                            }
                        }
                    }
                    other => {
                        return Err(CompileError::new(
                            ErrorKind::CFfi(format!(
                                "directive `@{}` is not valid on extern fns inside `link_extern`",
                                other
                            )),
                            d.span,
                        ));
                    }
                }
            }

            // ADR-0088: every extern fn must carry `@mark(unchecked)`.
            // FFI imports are unverified from the Gruel side by
            // construction; the marker makes the call-site discipline
            // visible — every caller must wrap the call in a
            // `checked { }` block.
            if !has_unchecked_mark {
                let fn_name = self.interner.resolve(&ext.name).to_string();
                let library = self.interner.resolve(&ext.library).to_string();
                return Err(CompileError::new(
                    ErrorKind::ExternFnMissingUnchecked { fn_name, library },
                    ext.span,
                ));
            }

            if self.functions.contains_key(&ext.name) {
                let name_str = self.interner.resolve(&ext.name).to_string();
                return Err(CompileError::new(
                    ErrorKind::DuplicateTypeDefinition {
                        type_name: format!("function `{}`", name_str),
                    },
                    ext.span,
                ));
            }

            self.functions.insert(
                ext.name,
                FunctionInfo {
                    params: params_range,
                    return_type: ret_type,
                    return_type_sym: ext.return_type,
                    body: InstRef::from_raw(u32::MAX),
                    span: ext.span,
                    is_generic: false,
                    is_pub: true,
                    // ADR-0088: every extern fn that carries
                    // `@mark(unchecked)` is treated as unchecked at
                    // call sites — every call must sit inside a
                    // `checked { }` block.
                    is_unchecked: has_unchecked_mark,
                    file_id: ext.span.file_id,
                    canonical_name: None,
                    link_library: Some(ext.library),
                    link_name: link_name_override,
                    is_extern: true,
                    is_c_abi: true,
                },
            );
        }
        Ok(())
    }

    /// Collect a function signature for forward reference.
    fn collect_function_signature(
        &mut self,
        name: Spur,
        (params_start, params_len): (u32, u32),
        return_type_sym: Spur,
        body: InstRef,
        span: Span,
        flags: FnFlags,
    ) -> CompileResult<()> {
        let FnFlags {
            is_pub,
            is_unchecked,
            directives_start,
            directives_len,
        } = flags;

        // ADR-0085: scan directives for `@mark(c)` (C ABI export) and
        // `@link_name("…")` (symbol override). Other markers and
        // directives are handled by their own passes; this is just the
        // C-FFI subset.
        //
        // ADR-0088: `@mark(unchecked)` on a fn / method is gated by the
        // `UncheckedFnExtensions` preview feature; the gate fires
        // centrally in `validate_directives`. The legacy `unchecked`
        // keyword path is unaffected.
        let mut is_c_abi = false;
        let mut link_name_override: Option<Spur> = None;
        let directives = self.rir.get_directives(directives_start, directives_len);
        for d in directives.iter() {
            let dir_name = self.interner.resolve(&d.name).to_string();
            match dir_name.as_str() {
                "mark" => {
                    for arg in &d.args {
                        let marker_name = self.interner.resolve(arg);
                        if marker_name == "c" {
                            is_c_abi = true;
                        }
                    }
                }
                "link_name" => {
                    if d.args.len() != 1 {
                        return Err(CompileError::new(
                            ErrorKind::CFfi(
                                "`@link_name(\"…\")` takes exactly one string argument".to_string(),
                            ),
                            d.span,
                        ));
                    }
                    link_name_override = Some(d.args[0]);
                }
                _ => {}
            }
        }

        // ADR-0085: `@link_name` is only valid on C-ABI fns (extern
        // declarations or `@mark(c)` exports).
        if link_name_override.is_some() && !is_c_abi {
            return Err(CompileError::new(
                ErrorKind::CFfi(
                    "`@link_name(\"…\")` is only valid on `@mark(c)` functions \
                     or extern fns inside `link_extern`"
                        .to_string(),
                ),
                span,
            ));
        }
        let params = self.rir.get_params(params_start, params_len);

        let param_names: Vec<Spur> = params.iter().map(|p| p.name).collect();

        // Check if this function has any comptime TYPE parameters (not value parameters).
        // A type parameter is a comptime param whose declared type is either:
        // - `type` (unbounded): `comptime T: type`
        // - a registered interface name (ADR-0056): `comptime T: SomeInterface`
        //
        // Both cases erase the parameter at codegen and substitute the
        // concrete type at specialization. Interface-bounded parameters
        // additionally trigger a conformance check at the call site.
        let type_sym = self.interner.get_or_intern("type");
        // Pre-compute per-param flags so the closure doesn't need to borrow
        // `self` (which conflicts with the resolve_type call below).
        let is_type_param: Vec<bool> = params
            .iter()
            .map(|p| p.is_comptime && (p.ty == type_sym || self.interfaces.contains_key(&p.ty)))
            .collect();
        // Any comptime parameter — type or value — makes the function generic.
        // Comptime value parameters (e.g. `comptime n: i32`) need per-call
        // specialization too: the body may contain a `comptime if n < 0 {…}`
        // guard that can only be evaluated once `n` is bound to a concrete
        // value at the call site.
        let is_generic = params.iter().any(|p| p.is_comptime);

        // Collect type parameter names.
        let type_param_names: Vec<Spur> = params
            .iter()
            .zip(is_type_param.iter())
            .filter_map(|(p, &b)| if b { Some(p.name) } else { None })
            .collect();

        // Record any interface bounds for use at specialization time.
        for p in params.iter() {
            if p.is_comptime
                && let Some(iid) = self.interfaces.get(&p.ty).copied()
            {
                self.comptime_interface_bounds.insert((name, p.name), iid);
            }
        }

        // For generic functions, we defer type resolution of type parameters until specialization.
        // We use Type::COMPTIME_TYPE as a placeholder for comptime type parameters.
        // ADR-0076 Phase 2: also collect the (possibly normalized) param mode
        // returned by `resolve_param_type` so `Ref(I)` / `MutRef(I)` lower to
        // the same `(Interface, Borrow|Inout)` shape as legacy `borrow t: I`
        // / `inout t: I`.
        //
        // A parameter type "references" a type parameter when bare equality
        // misses but a substituted resolution succeeds — e.g. `MutRef(Vec(T))`
        // mentions `T` indirectly. Treat those exactly like the bare-name
        // case: resolve at specialization, placeholder here. Mirrors the
        // `references_method_type_param` helper used for inline methods.
        let references_type_param = |ty_sym: Spur, sema: &mut Self| -> bool {
            if type_param_names.contains(&ty_sym) {
                return true;
            }
            if type_param_names.is_empty() {
                return false;
            }
            let subst: rustc_hash::FxHashMap<Spur, Type> =
                type_param_names.iter().map(|&n| (n, Type::I32)).collect();
            let with_subst = sema.resolve_type_for_comptime_with_subst(ty_sym, &subst);
            let without_subst =
                sema.resolve_type_for_comptime_with_subst(ty_sym, &HashMap::default());
            with_subst.is_some() && without_subst.is_none()
        };

        let mut param_types: Vec<Type> = Vec::with_capacity(params.len());
        let mut param_modes: Vec<RirParamMode> = Vec::with_capacity(params.len());
        for (p, &is_tp) in params.iter().zip(is_type_param.iter()) {
            let (ty, mode) = if is_tp || references_type_param(p.ty, self) {
                // Comptime type parameter, or a parameter whose declared type
                // is (or transitively contains) a type parameter — e.g.
                // `x: T`, `v: MutRef(Vec(T))`. The concrete type is resolved
                // at specialization; mode is taken verbatim from RIR.
                //
                // ADR-0076 normalization for the deferred case: when the
                // declared type is `Ref(...)` / `MutRef(...)` wrapping a
                // type parameter, surface that ref-shape on the param mode.
                // `resolve_param_type` does this for the eager path (and
                // for interface inner types); here we do the same shape
                // detection on the source-level symbol so the implicit-
                // forwarding logic in `analyze_call` (which can only see
                // the deferred `COMPTIME_TYPE` placeholder, not the
                // original `Ref(...)` shape) can still recognize the
                // reference parameter and promote the arg mode.
                let normalized_mode = {
                    let type_name = self.interner.resolve(&p.ty);
                    if let Some((callee, args)) = parse_type_call_syntax(type_name)
                        && args.len() == 1
                        && (callee == "Ref" || callee == "MutRef")
                        && matches!(p.mode, RirParamMode::Normal)
                    {
                        if callee == "MutRef" {
                            RirParamMode::MutRef
                        } else {
                            RirParamMode::Ref
                        }
                    } else {
                        p.mode
                    }
                };
                (Type::COMPTIME_TYPE, normalized_mode)
            } else {
                self.resolve_param_type(p.ty, p.mode, span)?
            };
            param_types.push(ty);
            param_modes.push(mode);
        }
        let param_comptime: Vec<bool> = params.iter().map(|p| p.is_comptime).collect();

        // Return type follows the same rule.
        let ret_type = if references_type_param(return_type_sym, self) {
            Type::COMPTIME_TYPE
        } else {
            self.resolve_type(return_type_sym, span)?
        };

        // Allocate parameter data in the arena
        let params_range =
            self.param_arena
                .alloc(param_names, param_types, param_modes, param_comptime);

        // ADR-0085: validate FFI types for `@mark(c)` exports — params
        // and return type must all be C-ABI compatible. Skipped for
        // regular Gruel fns.
        if is_c_abi {
            for ty in self.param_arena.types(params_range) {
                self.validate_ffi_type(*ty, "as a parameter type", span)?;
            }
            self.validate_ffi_type(ret_type, "as a return type", span)?;
        }

        self.functions.insert(
            name,
            FunctionInfo {
                params: params_range,
                return_type: ret_type,
                return_type_sym,
                body,
                span,
                is_generic,
                is_pub,
                is_unchecked,
                file_id: span.file_id,
                canonical_name: None,
                link_library: None,
                link_name: link_name_override,
                is_extern: false,
                is_c_abi,
            },
        );
        Ok(())
    }

    /// Collect methods defined inline in a struct.
    fn collect_struct_methods(
        &mut self,
        type_name: Spur,
        methods_start: u32,
        methods_len: u32,
        span: Span,
    ) -> CompileResult<()> {
        let struct_id = match self.structs.get(&type_name) {
            Some(id) => *id,
            None => {
                let type_name_str = self.interner.resolve(&type_name).to_string();
                return Err(CompileError::new(
                    ErrorKind::UnknownType(type_name_str),
                    span,
                ));
            }
        };
        let struct_type = Type::new_struct(struct_id);
        let drop_name_sym = self.interner.get_or_intern("__drop");

        // ADR-0076: bind `Self` to the host struct while resolving method
        // signatures. Errors abort the whole analysis pass so a leak is
        // harmless; on the success path we restore the previous binding.
        let saved_self = self.current_self.replace(struct_type);

        let methods = self.rir.get_inst_refs(methods_start, methods_len);
        for method_ref in methods {
            let method_inst = self.rir.get(method_ref);
            if let InstData::FnDecl {
                name: method_name,
                is_pub: method_is_pub,
                is_unchecked,
                params_start,
                params_len,
                return_type,
                body,
                has_self,
                receiver_mode,
                directives_start,
                directives_len,
                ..
            } = &method_inst.data
            {
                let receiver = decode_receiver_mode(*receiver_mode);

                // ADR-0088: reject `@mark(unchecked) fn __drop`. Drop
                // glue runs implicitly at scope exit; there is no
                // caller `checked { }` to gate it. The preview gate
                // itself fires centrally in `validate_directives`.
                if *method_name == drop_name_sym
                    && self.directives_have_mark_unchecked(*directives_start, *directives_len)
                {
                    return Err(CompileError::new(
                        ErrorKind::UncheckedDestructor,
                        method_inst.span,
                    ));
                }

                // ADR-0053: a method named `__drop` is the struct's destructor,
                // not a regular method. Route it through the destructor slot.
                if *method_name == drop_name_sym {
                    self.register_inline_struct_drop(
                        type_name,
                        struct_id,
                        DropSignature {
                            has_self: *has_self,
                            params_len: *params_len,
                            return_type: *return_type,
                            body: *body,
                            span: method_inst.span,
                        },
                    )?;
                    continue;
                }

                // Use StructId in key to support anonymous struct methods
                let key = (struct_id, *method_name);
                if self.methods.contains_key(&key) {
                    let type_name_str = self.interner.resolve(&type_name).to_string();
                    let method_name_str = self.interner.resolve(method_name).to_string();
                    return Err(CompileError::new(
                        ErrorKind::DuplicateMethod {
                            type_name: type_name_str,
                            method_name: method_name_str,
                        },
                        method_inst.span,
                    ));
                }

                let params = self.rir.get_params(*params_start, *params_len);
                let param_names: Vec<Spur> = params.iter().map(|p| p.name).collect();
                let param_comptime: Vec<bool> = params.iter().map(|p| p.is_comptime).collect();

                // Detect method-level comptime type parameters (e.g.,
                // `fn apply(self, comptime F: type, f: F) -> T`). When
                // present, the method is generic at the method level — its
                // param types that reference those names (`f: F`) and its
                // return type cannot be fully resolved until the method is
                // specialized at a call site. Mirrors the top-level
                // generic-function treatment above.
                //
                // ADR-0056: an interface-bounded comptime parameter
                // (`comptime T: SomeInterface`) is also a type parameter; we
                // record the bound for the conformance check at the call
                // site. The method-key is encoded as "StructName.method" to
                // share the bound side-table with top-level functions.
                let type_sym = self.interner.get_or_intern("type");
                let method_type_param_names: Vec<Spur> = params
                    .iter()
                    .filter(|p| {
                        p.is_comptime && (p.ty == type_sym || self.interfaces.contains_key(&p.ty))
                    })
                    .map(|p| p.name)
                    .collect();
                let is_method_generic = !method_type_param_names.is_empty();

                // Record interface bounds for this method.
                if !method_type_param_names.is_empty() {
                    let owner_str = format!(
                        "{}.{}",
                        self.interner.resolve(&type_name),
                        self.interner.resolve(method_name)
                    );
                    let owner = self.interner.get_or_intern(&owner_str);
                    for p in params.iter() {
                        if p.is_comptime
                            && let Some(iid) = self.interfaces.get(&p.ty).copied()
                        {
                            self.comptime_interface_bounds.insert((owner, p.name), iid);
                        }
                    }
                }

                // Helper: does a type symbol mention any of our method-level
                // type param names? Covers bare `T`, compound `[T; N]`,
                // `ptr const T`, etc. — check via the comptime-substitution
                // resolver using a sentinel substitution.
                let references_method_type_param = |ty_sym: Spur, sema: &mut Self| -> bool {
                    if method_type_param_names.contains(&ty_sym) {
                        return true;
                    }
                    let subst: rustc_hash::FxHashMap<Spur, Type> = method_type_param_names
                        .iter()
                        .map(|&n| (n, Type::I32))
                        .collect();
                    let with_subst = sema.resolve_type_for_comptime_with_subst(ty_sym, &subst);
                    let without_subst =
                        sema.resolve_type_for_comptime_with_subst(ty_sym, &HashMap::default());
                    with_subst.is_some() && without_subst.is_none()
                };

                // ADR-0076 Phase 2: collect normalized modes alongside types
                // so `Ref(I)` / `MutRef(I)` lower like the legacy keyword form.
                let mut param_types: Vec<Type> = Vec::with_capacity(params.len());
                let mut param_modes: Vec<RirParamMode> = Vec::with_capacity(params.len());
                for p in &params {
                    let (ty, mode) = if (p.is_comptime && p.ty == type_sym)
                        || references_method_type_param(p.ty, self)
                    {
                        (Type::COMPTIME_TYPE, p.mode)
                    } else {
                        self.resolve_param_type(p.ty, p.mode, method_inst.span)?
                    };
                    param_types.push(ty);
                    param_modes.push(mode);
                }
                let ret_type = if references_method_type_param(*return_type, self) {
                    Type::COMPTIME_TYPE
                } else {
                    self.resolve_type(*return_type, method_inst.span)?
                };

                // Allocate method parameters in the arena, preserving mode
                // and comptime flags so specialization can pick them up.
                let param_range =
                    self.param_arena
                        .alloc(param_names, param_types, param_modes, param_comptime);

                self.methods.insert(
                    key,
                    MethodInfo {
                        struct_type,
                        has_self: *has_self,
                        receiver,
                        params: param_range,
                        return_type: ret_type,
                        body: *body,
                        span: method_inst.span,
                        is_unchecked: *is_unchecked,
                        is_generic: is_method_generic,
                        return_type_sym: *return_type,
                        is_pub: *method_is_pub,
                        file_id: method_inst.span.file_id,
                    },
                );
            }
        }
        self.current_self = saved_self;
        Ok(())
    }

    /// Register an inline `fn __drop(self)` as a struct's destructor.
    ///
    /// Validates the signature (must be exactly `fn __drop(self)`, no extra
    /// params, returns unit) and the type's copy/linear status (a destructor
    /// is illegal on `@derive(Copy)` and `linear` types per ADR-0053).
    fn register_inline_struct_drop(
        &mut self,
        type_name: Spur,
        struct_id: StructId,
        sig: DropSignature,
    ) -> CompileResult<()> {
        let DropSignature {
            has_self,
            params_len,
            return_type,
            body,
            span,
        } = sig;
        let type_name_str = self.interner.resolve(&type_name).to_string();

        // Signature check: `fn __drop(self)`, no extra params, no non-unit return.
        if !has_self {
            return Err(CompileError::new(
                ErrorKind::InvalidInlineDrop {
                    type_name: type_name_str.clone(),
                    reason: "must take `self` — found an associated function".into(),
                },
                span,
            ));
        }
        if params_len > 0 {
            return Err(CompileError::new(
                ErrorKind::InvalidInlineDrop {
                    type_name: type_name_str.clone(),
                    reason: "must take only `self` — extra parameters are not allowed".into(),
                },
                span,
            ));
        }
        let ret_str = self.interner.resolve(&return_type);
        if ret_str != "()" {
            return Err(CompileError::new(
                ErrorKind::InvalidInlineDrop {
                    type_name: type_name_str.clone(),
                    reason: format!("must return unit — found return type `{}`", ret_str),
                },
                span,
            ));
        }

        // Affine-only: `@derive(Copy)` structs cannot have destructors (double-free risk).
        // `linear` structs cannot either — they are never implicitly dropped, so
        // a destructor would be unreachable.
        let struct_def_snapshot = self.type_pool.struct_def(struct_id);
        match struct_def_snapshot.posture {
            Posture::Copy => {
                return Err(CompileError::new(
                    ErrorKind::InvalidInlineDrop {
                        type_name: type_name_str.clone(),
                        reason:
                            "`@derive(Copy)` types cannot declare `fn __drop` (would double-free on copy)"
                                .into(),
                    },
                    span,
                ));
            }
            Posture::Linear => {
                return Err(CompileError::new(
                    ErrorKind::InvalidInlineDrop {
                        type_name: type_name_str.clone(),
                        reason: "`linear` types cannot declare `fn __drop` (linear values are never implicitly dropped)".into(),
                    },
                    span,
                ));
            }
            Posture::Affine => {}
        }

        // ADR-0085: `fn __drop` on `@mark(c)` structs is forbidden in
        // v1. The C side owns cross-boundary cleanup discipline; mixing
        // Gruel destructor semantics with raw extern calls is left to a
        // future ADR with defined cross-boundary semantics.
        if struct_def_snapshot.is_c_layout {
            return Err(CompileError::new(
                ErrorKind::CFfi(format!(
                    "`@mark(c) struct {}` cannot declare `fn __drop`; manual cleanup is required \
                     through raw pointer discipline",
                    type_name_str
                )),
                span,
            ));
        }

        // Only one destructor per type.
        let mut struct_def = struct_def_snapshot;
        if struct_def.destructor.is_some() {
            return Err(CompileError::new(
                ErrorKind::DuplicateDestructor {
                    type_name: type_name_str.clone(),
                },
                span,
            ));
        }
        let destructor_name = format!("{}.__drop", type_name_str);
        struct_def.destructor = Some(destructor_name);
        self.type_pool.update_struct_def(struct_id, struct_def);

        self.inline_struct_drops.insert(struct_id, (body, span));
        Ok(())
    }

    /// Register an inline `fn __drop(self)` as an enum's destructor (ADR-0053 phase 3b).
    ///
    /// Mirrors `register_inline_struct_drop`. Validates the signature
    /// (must be `fn __drop(self)` returning unit, only one per type) and
    /// stores the destructor metadata in `EnumDef.destructor`.
    fn register_inline_enum_drop(
        &mut self,
        type_name: Spur,
        enum_id: EnumId,
        sig: DropSignature,
    ) -> CompileResult<()> {
        let DropSignature {
            has_self,
            params_len,
            return_type,
            body,
            span,
        } = sig;
        let type_name_str = self.interner.resolve(&type_name).to_string();

        if !has_self {
            return Err(CompileError::new(
                ErrorKind::InvalidInlineDrop {
                    type_name: type_name_str,
                    reason: "must take `self` — found an associated function".into(),
                },
                span,
            ));
        }
        if params_len > 0 {
            return Err(CompileError::new(
                ErrorKind::InvalidInlineDrop {
                    type_name: type_name_str,
                    reason: "must take only `self` — extra parameters are not allowed".into(),
                },
                span,
            ));
        }
        let ret_str = self.interner.resolve(&return_type);
        if ret_str != "()" {
            return Err(CompileError::new(
                ErrorKind::InvalidInlineDrop {
                    type_name: type_name_str,
                    reason: format!("must return unit — found return type `{}`", ret_str),
                },
                span,
            ));
        }

        let mut enum_def = self.type_pool.enum_def(enum_id);
        if enum_def.destructor.is_some() {
            return Err(CompileError::new(
                ErrorKind::DuplicateDestructor {
                    type_name: type_name_str,
                },
                span,
            ));
        }
        let destructor_name = format!("{}.__drop", type_name_str);
        enum_def.destructor = Some(destructor_name);
        self.type_pool.update_enum_def(enum_id, enum_def);

        self.inline_enum_drops.insert(enum_id, (body, span));
        Ok(())
    }

    /// Collect methods defined inline in a named enum (ADR-0053).
    ///
    /// Mirrors `collect_struct_methods`: registers each method against the
    /// enum's `EnumId` in `self.enum_methods`, which the method-resolution
    /// machinery already consults for anonymous enums (ADR-0039).
    fn collect_enum_methods(
        &mut self,
        type_name: Spur,
        methods_start: u32,
        methods_len: u32,
        span: Span,
    ) -> CompileResult<()> {
        if methods_len == 0 {
            return Ok(());
        }
        let enum_id = match self.enums.get(&type_name) {
            Some(id) => *id,
            None => {
                let type_name_str = self.interner.resolve(&type_name).to_string();
                return Err(CompileError::new(
                    ErrorKind::UnknownType(type_name_str),
                    span,
                ));
            }
        };
        let enum_type = Type::new_enum(enum_id);
        let drop_name_sym = self.interner.get_or_intern("__drop");

        // ADR-0076: bind `Self` to the host enum while resolving method
        // signatures.
        let saved_self = self.current_self.replace(enum_type);

        let methods = self.rir.get_inst_refs(methods_start, methods_len);
        for method_ref in methods {
            let method_inst = self.rir.get(method_ref);
            if let InstData::FnDecl {
                name: method_name,
                is_pub: method_is_pub,
                is_unchecked,
                params_start,
                params_len,
                return_type,
                body,
                has_self,
                receiver_mode,
                directives_start,
                directives_len,
                ..
            } = &method_inst.data
            {
                let receiver = decode_receiver_mode(*receiver_mode);

                // ADR-0088: reject `@mark(unchecked) fn __drop`.
                if *method_name == drop_name_sym
                    && self.directives_have_mark_unchecked(*directives_start, *directives_len)
                {
                    return Err(CompileError::new(
                        ErrorKind::UncheckedDestructor,
                        method_inst.span,
                    ));
                }

                // ADR-0053 phase 3b: a method named `__drop` is the enum's destructor,
                // not a regular method. Route it through the per-enum destructor slot.
                if *method_name == drop_name_sym {
                    self.register_inline_enum_drop(
                        type_name,
                        enum_id,
                        DropSignature {
                            has_self: *has_self,
                            params_len: *params_len,
                            return_type: *return_type,
                            body: *body,
                            span: method_inst.span,
                        },
                    )?;
                    continue;
                }
                let key = (enum_id, *method_name);
                if self.enum_methods.contains_key(&key) {
                    let type_name_str = self.interner.resolve(&type_name).to_string();
                    let method_name_str = self.interner.resolve(method_name).to_string();
                    return Err(CompileError::new(
                        ErrorKind::DuplicateMethod {
                            type_name: type_name_str,
                            method_name: method_name_str,
                        },
                        method_inst.span,
                    ));
                }

                let params = self.rir.get_params(*params_start, *params_len);
                let param_names: Vec<Spur> = params.iter().map(|p| p.name).collect();
                let param_types: Vec<Type> = params
                    .iter()
                    .map(|p| self.resolve_type(p.ty, method_inst.span))
                    .collect::<CompileResult<Vec<_>>>()?;
                let ret_type = self.resolve_type(*return_type, method_inst.span)?;

                let param_range = self
                    .param_arena
                    .alloc_method(param_names.into_iter(), param_types.into_iter());

                self.enum_methods.insert(
                    key,
                    MethodInfo {
                        struct_type: enum_type,
                        has_self: *has_self,
                        receiver,
                        params: param_range,
                        return_type: ret_type,
                        body: *body,
                        span: method_inst.span,
                        is_unchecked: *is_unchecked,
                        // Enum methods do not yet support method-level
                        // comptime type params (ADR-0055 defers that path).
                        is_generic: false,
                        return_type_sym: *return_type,
                        is_pub: *method_is_pub,
                        file_id: method_inst.span.file_id,
                    },
                );
            }
        }
        self.current_self = saved_self;
        Ok(())
    }

    /// Collect a constant declaration.
    ///
    /// Constants are compile-time values. In the module system, they're primarily
    /// used for re-exports:
    /// ```gruel
    /// pub const strings = @import("utils/strings.gruel");
    /// ```
    ///
    /// When the initializer is an `@import(...)`, we evaluate it at compile time
    /// to resolve the module and register it in the module registry. This enables
    /// subsequent member access via `const_name.function()` syntax.
    fn collect_const_declaration(
        &mut self,
        name: Spur,
        is_pub: bool,
        init: InstRef,
        span: Span,
    ) -> CompileResult<()> {
        // ADR-0078: detect item-level re-exports first. `pub const X = mod.Y`
        // makes X an alias for `mod.Y`, registering it in the appropriate
        // name table (functions/structs/enums/interfaces) so call sites
        // can use X transparently. The fallback path below handles
        // `pub const X = @import("...")` (whole-module re-export) and
        // primitive constants.
        if self.try_collect_reexport(name, is_pub, init, span)? {
            return Ok(());
        }

        let name_str = self.interner.resolve(&name).to_string();

        // Check for duplicate constant names
        if self.constants.contains_key(&name) {
            return Err(CompileError::new(
                ErrorKind::DuplicateConstant {
                    name: name_str,
                    kind: "constant".to_string(),
                },
                span,
            ));
        }

        // Check for collision with function names
        if self.functions.contains_key(&name) {
            return Err(CompileError::new(
                ErrorKind::DuplicateConstant {
                    name: name_str.clone(),
                    kind: "constant (conflicts with function)".to_string(),
                },
                span,
            ));
        }

        // Evaluate the initializer at compile time to determine the constant type.
        let const_type = self.evaluate_const_init(init, span)?;

        self.constants.insert(
            name,
            ConstInfo {
                is_pub,
                ty: const_type,
                init,
                span,
            },
        );

        Ok(())
    }

    /// ADR-0078: Try to handle an item-level re-export of the form
    /// `pub const X = some_module_const.Y`. Returns `Ok(true)` if the
    /// constant was recognized as a re-export and registered as an alias;
    /// `Ok(false)` if this isn't a re-export and the regular const path
    /// should run; `Err(...)` if it looks like a re-export but the item
    /// can't be resolved.
    fn try_collect_reexport(
        &mut self,
        name: Spur,
        is_pub: bool,
        init: InstRef,
        span: Span,
    ) -> CompileResult<bool> {
        let inst = self.rir.get(init);
        let InstData::FieldGet { base, field } = &inst.data else {
            return Ok(false);
        };
        let field = *field;

        // The base must be a `VarRef` to a const that holds a module.
        let base_inst = self.rir.get(*base);
        let InstData::VarRef { name: base_name } = &base_inst.data else {
            return Ok(false);
        };
        let module_id = match self.constants.get(base_name).and_then(|c| c.ty.as_module()) {
            Some(id) => id,
            None => return Ok(false),
        };
        let module_file_path = self.module_registry.get_def(module_id).file_path.clone();
        let same_name = name == field;

        // Look the field up across each item kind, restricted to items
        // declared in the imported module's file.

        // Function.
        if let Some(fn_info) = self.functions.get(&field).copied() {
            let fn_path = self
                .get_file_path(fn_info.file_id)
                .map(|s| s.to_string())
                .unwrap_or_default();
            if fn_path == module_file_path {
                if !same_name {
                    self.check_alias_collision(name, span)?;
                    // Resolve to the canonical (non-aliased) name so chains
                    // of re-exports collapse to the original function symbol.
                    let canonical = fn_info.canonical_name.unwrap_or(field);
                    let alias = FunctionInfo {
                        is_pub,
                        canonical_name: Some(canonical),
                        ..fn_info
                    };
                    self.functions.insert(name, alias);
                }
                return Ok(true);
            }
        }

        // Struct.
        if let Some(&struct_id) = self.structs.get(&field) {
            let s_path = self
                .get_file_path(self.type_pool.struct_def(struct_id).file_id)
                .map(|s| s.to_string())
                .unwrap_or_default();
            if s_path == module_file_path {
                if !same_name {
                    self.check_alias_collision(name, span)?;
                    self.structs.insert(name, struct_id);
                }
                return Ok(true);
            }
        }

        // Enum.
        if let Some(&enum_id) = self.enums.get(&field) {
            let e_path = self
                .get_file_path(self.type_pool.enum_def(enum_id).file_id)
                .map(|s| s.to_string())
                .unwrap_or_default();
            if e_path == module_file_path {
                if !same_name {
                    self.check_alias_collision(name, span)?;
                    self.enums.insert(name, enum_id);
                }
                return Ok(true);
            }
        }

        // Interface.
        if let Some(&iface_id) = self.interfaces.get(&field) {
            let iface_def = &self.interface_defs[iface_id.0 as usize];
            let i_path = self
                .get_file_path(iface_def.file_id)
                .map(|s| s.to_string())
                .unwrap_or_default();
            if i_path == module_file_path {
                if !same_name {
                    self.check_alias_collision(name, span)?;
                    self.interfaces.insert(name, iface_id);
                }
                return Ok(true);
            }
        }

        // Field exists in the module's namespace but doesn't resolve to a
        // re-exportable item. Could be e.g. `mod.NotAnItem` — surface as a
        // standard "unknown module member" error.
        let module_def = self.module_registry.get_def(module_id);
        let module_name = module_def.import_path.clone();
        let field_str = self.interner.resolve(&field).to_string();
        Err(CompileError::new(
            ErrorKind::UnknownModuleMember {
                module_name,
                member_name: field_str,
            },
            span,
        ))
    }

    /// Collision check for a re-export alias. The alias name must not
    /// shadow an existing function/struct/enum/interface/constant.
    fn check_alias_collision(&self, name: Spur, span: Span) -> CompileResult<()> {
        let name_str = self.interner.resolve(&name).to_string();
        if self.functions.contains_key(&name)
            || self.structs.contains_key(&name)
            || self.enums.contains_key(&name)
            || self.interfaces.contains_key(&name)
            || self.constants.contains_key(&name)
        {
            return Err(CompileError::new(
                ErrorKind::DuplicateConstant {
                    name: name_str,
                    kind: "re-export alias".to_string(),
                },
                span,
            ));
        }
        Ok(())
    }

    /// Evaluate a constant initializer at compile time.
    ///
    /// Currently handles:
    /// - `@import("path")` - Returns Type::Module
    /// - Integer literals - Returns the integer type
    ///
    /// Future extensions (ADR-0025 comptime) will support:
    /// - Arithmetic on constants
    /// - comptime blocks
    /// - comptime function calls
    fn evaluate_const_init(&mut self, init: InstRef, span: Span) -> CompileResult<Type> {
        let init_inst = self.rir.get(init);

        match &init_inst.data {
            // @import("path") evaluates to Type::Module at compile time
            InstData::Intrinsic {
                name,
                args_start,
                args_len,
            } => {
                if *name == self.known.import {
                    // Validate exactly one argument
                    if *args_len != 1 {
                        return Err(CompileError::new(
                            ErrorKind::IntrinsicWrongArgCount {
                                name: "import".to_string(),
                                expected: 1,
                                found: *args_len as usize,
                            },
                            span,
                        ));
                    }

                    // Accept a string literal or a comptime_str expression.
                    let arg_refs = self.rir.get_inst_refs(*args_start, *args_len);
                    let import_path = self.resolve_import_path_arg(arg_refs[0])?;

                    // Resolve the import path to an absolute file path
                    let resolved_path = self.resolve_import_path(&import_path, span)?;

                    // Register the module in the registry
                    let (module_id, _is_new) = self
                        .module_registry
                        .get_or_create(import_path, resolved_path);

                    Ok(Type::new_module(module_id))
                } else {
                    // For other intrinsics in const context, we don't support them yet
                    let intrinsic_name = self.interner.resolve(name).to_string();
                    Err(CompileError::new(
                        ErrorKind::ConstExprNotSupported {
                            expr_kind: format!("@{} intrinsic", intrinsic_name),
                        },
                        span,
                    ))
                }
            }

            // Integer literals evaluate to i32 (the default integer type)
            // Note: RIR doesn't distinguish between integer types at this level;
            // type inference happens later. For now, we treat all integer consts as i32.
            InstData::IntConst(_) => Ok(Type::I32),

            // Boolean literals
            InstData::BoolConst(_) => Ok(Type::BOOL),

            // Unit literal
            InstData::UnitConst => Ok(Type::UNIT),

            // String literals
            InstData::StringConst(_) => {
                // String constants would need the String type
                // For now, we don't support them in const context
                Err(CompileError::new(
                    ErrorKind::ConstExprNotSupported {
                        expr_kind: "string literals".to_string(),
                    },
                    span,
                ))
            }

            // Other expressions are not yet supported in const context
            _ => Err(CompileError::new(
                ErrorKind::ConstExprNotSupported {
                    expr_kind: "this expression".to_string(),
                },
                span,
            )),
        }
    }
}

/// Build the trailing note for an unknown-directive error (ADR-0075).
///
/// Retired directives get a targeted retirement message pointing at the
/// ADR that took them out of service. Other names get an edit-distance
/// hint when there's a near-match in the recognized set; otherwise no
/// note is attached.
fn directive_diagnosis_note(name: &str) -> Option<String> {
    match name {
        "handle" => {
            return Some(
                "the `@handle` directive was retired in ADR-0075; \
                 conform to the `Handle` interface by defining \
                 `fn handle(self: Ref(Self)) -> Self` directly"
                    .to_string(),
            );
        }
        "copy" => {
            return Some(
                "the `@copy` directive was retired in ADR-0059; \
                 use `@derive(Copy)` instead"
                    .to_string(),
            );
        }
        _ => {}
    }

    const RECOGNIZED: &[&str] = &["allow", "derive", "mark"];
    RECOGNIZED
        .iter()
        .map(|cand| (cand, levenshtein_distance(name, cand)))
        .filter(|(_, d)| *d <= 2)
        .min_by_key(|(_, d)| *d)
        .map(|(cand, _)| format!("did you mean `@{cand}`?"))
}

/// ADR-0083: edit-distance suggestion for a typo'd marker name.
///
/// Returns a "did you mean `X`?" hint when there's a near-match in the
/// `BUILTIN_MARKERS` registry, otherwise emits a list of the recognized
/// markers so users see what's available.
fn marker_diagnosis_note(name: &str) -> Option<String> {
    let names: Vec<&'static str> = BUILTIN_MARKERS.iter().map(|m| m.name).collect();
    if let Some(suggestion) = names
        .iter()
        .map(|cand| (*cand, levenshtein_distance(name, cand)))
        .filter(|(_, d)| *d <= 2)
        .min_by_key(|(_, d)| *d)
        .map(|(cand, _)| cand)
    {
        return Some(format!("did you mean `{suggestion}`?"));
    }
    Some(format!("recognized markers: {}", names.join(", ")))
}

/// Wagner-Fischer Levenshtein distance. Used by `directive_diagnosis_note`
/// to suggest near-matches for typo'd directive names. Both inputs are
/// short identifiers (~10 chars), so the O(n·m) cost is negligible and the
/// dependency-free implementation is preferable to pulling in `strsim`.
fn levenshtein_distance(a: &str, b: &str) -> usize {
    let a: Vec<char> = a.chars().collect();
    let b: Vec<char> = b.chars().collect();
    let (n, m) = (a.len(), b.len());
    if n == 0 {
        return m;
    }
    if m == 0 {
        return n;
    }
    let mut prev: Vec<usize> = (0..=m).collect();
    let mut curr: Vec<usize> = vec![0; m + 1];
    for i in 1..=n {
        curr[0] = i;
        for j in 1..=m {
            let cost = if a[i - 1] == b[j - 1] { 0 } else { 1 };
            curr[j] = (curr[j - 1] + 1).min(prev[j] + 1).min(prev[j - 1] + cost);
        }
        std::mem::swap(&mut prev, &mut curr);
    }
    prev[m]
}

#[cfg(test)]
mod directive_validation_tests {
    use super::{directive_diagnosis_note, levenshtein_distance};

    #[test]
    fn levenshtein_basics() {
        assert_eq!(levenshtein_distance("kitten", "sitting"), 3);
        assert_eq!(levenshtein_distance("allow", "allwo"), 2);
        assert_eq!(levenshtein_distance("derive", "dervie"), 2);
        assert_eq!(levenshtein_distance("derive", "derive"), 0);
        assert_eq!(levenshtein_distance("", "abc"), 3);
        assert_eq!(levenshtein_distance("abc", ""), 3);
    }

    #[test]
    fn note_for_typo_near_allow() {
        let note = directive_diagnosis_note("allwo").expect("near-match should suggest");
        assert!(note.contains("@allow"), "got: {note}");
    }

    #[test]
    fn note_for_typo_near_derive() {
        let note = directive_diagnosis_note("dervie").expect("near-match should suggest");
        assert!(note.contains("@derive"), "got: {note}");
    }

    #[test]
    fn note_for_far_typo_is_none() {
        assert!(directive_diagnosis_note("xyzzy").is_none());
    }

    #[test]
    fn note_for_retired_handle_mentions_adr_0075() {
        let note = directive_diagnosis_note("handle").expect("retirement note");
        assert!(note.contains("ADR-0075"), "got: {note}");
        assert!(note.contains("Handle"), "got: {note}");
    }

    #[test]
    fn note_for_retired_copy_mentions_adr_0059() {
        let note = directive_diagnosis_note("copy").expect("retirement note");
        assert!(note.contains("ADR-0059"), "got: {note}");
        assert!(note.contains("@derive(Copy)"), "got: {note}");
    }
}