plum

// Functions/methods are named camelCase across this project (matching plum's own

// naming convention), not Rust's idiomatic snake_case — silence the resulting lint.

#![allow(non_snake_case)]

use wasm_encoder::*;

use std::cell::RefCell;

use std::collections::{HashMap, HashSet};

use plum_core::ast;

use plum_checker::types::{PlumType, TypeEnv, TypeScheme};

use plum_checker::{ClassEnv, MethodEnv, EnumVariants, EnumVariantInfo, EnumParams};

/// One entry in the module's type section. Wasm's type section is a SINGLE shared

/// index space for function types AND (once wasm-gc is in play) composite

/// struct/array types — `Rec` entries occupy as many consecutive indices as they

/// have members, exactly like `CoreTypeEncoder::rec` groups multiple sub-types

/// under one recursive-group declaration.

enum TypeEntry {

    Func(FuncType),

    /// A whole `rec` group of struct/array sub-types, declared together so members

    /// can reference each other (including themselves) regardless of declaration

    /// order within the group.

    Rec(Vec<SubType>),

}

/// One entry in the module's data section. Like the type section, data segments

/// share ONE index space regardless of kind — a `Passive` segment's index (needed by

/// `array.new_data`) is its position among ALL segments, active or passive.

enum DataSegmentEntry {

    Active(u32, Vec<u8>),

    Passive(Vec<u8>),

}

pub struct WasmModule {

    types: Vec<TypeEntry>,

    /// Running count of type-section INDICES assigned so far — NOT the same as

    /// `types.len()`, since one `TypeEntry::Rec` occupies as many indices as it has

    /// members while still being a single `Vec` element.

    next_type_idx: u32,

    imports: Vec<(String, String, u32)>,

    functions: Vec<(u32, Vec<u8>)>,

    exports: Vec<(String, ExportKind, u32)>,

    globals: Vec<(ValType, bool, Vec<u8>)>,

    data_segments: Vec<DataSegmentEntry>,

    /// Function indices, in table order — the single funcref table used for

    /// closure `call_indirect` dispatch. Index into this vec IS the table index.

    table_elements: Vec<u32>,

    pub func_import_count: u32,

    pub func_count: u32,

    global_count: u32,

    start_function: Option<u32>,

}

impl WasmModule {

    pub fn new() -> Self {

        Self {

            types: Vec::new(),

            next_type_idx: 0,

            imports: Vec::new(),

            functions: Vec::new(),

            exports: Vec::new(),

            globals: Vec::new(),

            data_segments: Vec::new(),

            table_elements: Vec::new(),

            func_import_count: 0,

            func_count: 0,

            global_count: 0,

            start_function: None,

        }

    }

    pub fn addType(&mut self, params: &[ValType], results: &[ValType]) -> u32 {

        let idx = self.next_type_idx;

        self.types.push(TypeEntry::Func(FuncType::new(params.iter().copied(), results.iter().copied())));

        self.next_type_idx += 1;

        idx

    }

    /// Declares a whole `rec` group of wasm-gc struct/array sub-types together,

    /// returning the type index assigned to each member, in order. Grouping

    /// unrelated types is harmless — the point is that MUTUALLY referencing types

    /// (e.g. an enum's supertype and its variant subtypes, or a self-referential

    /// struct field) MUST share a `rec` group to reference each other regardless of

    /// which one is declared "first".

    pub fn addGcTypes(&mut self, subtypes: Vec<SubType>) -> Vec<u32> {

        let base = self.next_type_idx;

        let count = subtypes.len() as u32;

        self.types.push(TypeEntry::Rec(subtypes));

        self.next_type_idx += count;

        (base..base + count).collect()

    }

    pub fn addImport(&mut self, module: &str, name: &str, type_idx: u32) -> u32 {

        let idx = self.func_import_count;

        self.imports.push((module.to_string(), name.to_string(), type_idx));

        self.func_import_count += 1;

        idx

    }

    pub fn addFunction(&mut self, type_idx: u32, body: &[u8]) -> u32 {

        let idx = self.func_import_count + self.func_count;

        self.functions.push((type_idx, body.to_vec()));

        self.func_count += 1;

        idx

    }

    pub fn addExport(&mut self, name: &str, kind: ExportKind, idx: u32) {

        self.exports.push((name.to_string(), kind, idx));

    }

    pub fn addGlobal(&mut self, val_type: ValType, mutable: bool, init: &[u8]) -> u32 {

        let idx = self.global_count;

        self.globals.push((val_type, mutable, init.to_vec()));

        self.global_count += 1;

        idx

    }

    pub fn addDataSegment(&mut self, offset: u32, data: &[u8]) {

        self.data_segments.push(DataSegmentEntry::Active(offset, data.to_vec()));

    }

    /// Adds a passive segment (no implicit memory-init offset) and returns its index

    /// in the shared active/passive data-segment index space — the index `array.new_data`

    /// needs to reference it. Passive segments require a `DataCountSection` (see `finish`).

    pub fn addPassiveDataSegment(&mut self, data: &[u8]) -> u32 {

        let idx = self.data_segments.len() as u32;

        self.data_segments.push(DataSegmentEntry::Passive(data.to_vec()));

        idx

    }

    /// Registers `func_idx` to run once automatically at instantiation, before any

    /// export is callable — needed because `struct.new` (and therefore constructing

    /// any GC singleton, like the pre-allocated payload-free enum variants) is not

    /// allowed inside a `global`'s own const-expr initializer (confirmed empirically

    /// in Task 1 — `wasmtimeGcConfigAllowsStructNewInGlobalConstExpr` fails), so those

    /// globals are declared `mutable` with a `ref.null` initial value and populated

    /// here instead.

    pub fn setStartFunction(&mut self, func_idx: u32) {

        self.start_function = Some(func_idx);

    }

    /// Registers `func_idx` as the next slot in the single funcref table used for

    /// closure `call_indirect` dispatch, returning its table index.

    pub fn addTableElement(&mut self, func_idx: u32) -> u32 {

        let table_idx = self.table_elements.len() as u32;

        self.table_elements.push(func_idx);

        table_idx

    }

    pub fn finish(&mut self) -> Vec<u8> {

        let mut module = wasm_encoder::Module::new();

        // Type section

        let mut types = TypeSection::new();

        for entry in &self.types {

            match entry {

                TypeEntry::Func(ft) => {

                    types.ty().function(ft.params().iter().copied(), ft.results().iter().copied());

                }

                TypeEntry::Rec(subtypes) => {

                    types.ty().rec(subtypes.iter().cloned());

                }

            }

        }

        module.section(&types);

        // Import section

        if !self.imports.is_empty() {

            let mut imports = ImportSection::new();

            for (module_name, name, type_idx) in &self.imports {

                imports.import(module_name, name, EntityType::Function(*type_idx));

            }

            module.section(&imports);

        }

        // Function section

        if !self.functions.is_empty() {

            let mut funcs = FunctionSection::new();

            for (type_idx, _) in &self.functions {

                funcs.function(*type_idx);

            }

            module.section(&funcs);

        }

        // Table section

        if !self.table_elements.is_empty() {

            let mut tables = TableSection::new();

            tables.table(TableType {

                element_type: RefType::FUNCREF,

                minimum: self.table_elements.len() as u64,

                maximum: Some(self.table_elements.len() as u64),

                table64: false,

                shared: false,

            });

            module.section(&tables);

        }

        // Global section

        if !self.globals.is_empty() {

            let mut globals = GlobalSection::new();

            for (val_type, mutable, init_expr) in &self.globals {

                let expr = ConstExpr::raw(init_expr.iter().copied());

                globals.global(

                    GlobalType { val_type: *val_type, mutable: *mutable, shared: false },

                    &expr,

                );

            }

            module.section(&globals);

        }

        // Export section

        if !self.exports.is_empty() {

            let mut exports = ExportSection::new();

            for (name, kind, idx) in &self.exports {

                exports.export(name, *kind, *idx);

            }

            module.section(&exports);

        }

        // Start section

        if let Some(func_idx) = self.start_function {

            module.section(&StartSection { function_index: func_idx });

        }

        // Element section

        if !self.table_elements.is_empty() {

            let mut elements = ElementSection::new();

            let offset = ConstExpr::i32_const(0);

            elements.active(Some(0), &offset, Elements::Functions(std::borrow::Cow::Borrowed(&self.table_elements)));

            module.section(&elements);

        }

        // DataCount section — required whenever `array.new_data`/`data.drop` reference

        // a passive segment, and must appear before the code section.

        let has_passive = self.data_segments.iter().any(|e| matches!(e, DataSegmentEntry::Passive(_)));

        if has_passive {

            module.section(&DataCountSection { count: self.data_segments.len() as u32 });

        }

        // Code section

        if !self.functions.is_empty() {

            let mut code = CodeSection::new();

            for (_, body_bytes) in &self.functions {

                code.raw(body_bytes);

            }

            module.section(&code);

        }

        // Data section

        if !self.data_segments.is_empty() {

            let mut data = DataSection::new();

            for entry in &self.data_segments {

                match entry {

                    DataSegmentEntry::Active(offset, bytes) => {

                        let offset_expr = ConstExpr::i32_const(*offset as i32);

                        data.active(0, &offset_expr, bytes.iter().copied());

                    }

                    DataSegmentEntry::Passive(bytes) => {

                        data.passive(bytes.iter().copied());

                    }

                }

            }

            module.section(&data);

        }

        module.finish()

    }

}

impl Default for WasmModule {

    fn default() -> Self {

        Self::new()

    }

}

#[derive(Clone)]

pub struct FuncSig {

    pub params: Vec<ValType>,

    pub ret: Option<ValType>,

}

/// Everything codegen needs to know about one closure *literal* found in the program.

/// wasm has no native closures: each literal `|v| body` becomes its own real wasm

/// function (registered in the funcref table), and a closure *value* is a `ref` to

/// the shared `{table_idx: i32, env: anyref}` struct (`GcTypeRegistry::closure_type_idx`).

/// `env` is a `ref.cast` of this closure literal's OWN env struct type

/// (`env_type_idx`), one field per captured (free) variable in `free_vars` order.

pub struct ClosureInfo {

    /// Reserved wasm function index for this closure's compiled body.

    pub func_idx: u32,

    /// Index of `func_idx` in the funcref table (the `i32` stored in the closure

    /// struct's `table_idx` field).

    pub table_idx: u32,

    /// This closure literal's own env struct type index (fields = `free_vars`, in

    /// order) — assigned once all closures are discovered, alongside every other

    /// closure's env type and the shared closure-value struct, in one `rec` group.

    pub env_type_idx: u32,

    /// Closure param val types (NOT including the implicit leading env pointer).

    pub param_vts: Vec<ValType>,

    /// Closure param plum types (for the closure body's own type env).

    pub param_ptypes: Vec<PlumType>,

    /// Closure return val type (`None` for a `Unit`-returning closure).

    pub ret_vt: Option<ValType>,

    /// Free variables captured by value, in a stable (first-appearance) order; the

    /// index into this vec IS the variable's field index in the env struct.

    pub free_vars: Vec<(String, PlumType)>,

}

/// Key for deduplicating `call_indirect` function-type indices: the full wasm

/// signature (leading env-ptr param included) of a closure.

type ClosureSigKey = (Vec<ValType>, Option<ValType>);

/// Global, read-only lookup tables shared by every function body being compiled.

pub struct CompileCtx<'a> {

    pub func_ids: HashMap<String, u32>,

    pub func_sigs: HashMap<String, FuncSig>,

    pub classes: ClassEnv,

    pub methods: MethodEnv,

    pub enum_variants: EnumVariants,

    pub enum_params: EnumParams,

    pub global_env: TypeEnv,

    /// Closure literal (keyed by `&Expr::Closure` pointer identity) -> its `ClosureInfo`.

    pub closures: HashMap<usize, ClosureInfo>,

    /// The AST of each discovered closure literal, keyed the same way, so its body can

    /// be compiled in a second pass after all closures are registered.

    pub closure_asts: HashMap<usize, &'a ast::Closure>,

    /// Closure wasm signature -> function-type index, for `call_indirect` at call sites.

    pub closure_call_types: HashMap<ClosureSigKey, u32>,

    /// Top-level function name -> global index holding its zero-capture "trampoline"

    /// closure struct `{table_idx, env=null}`, for using a plain named function

    /// wherever a `fn(...)`-typed value is expected (e.g. `each(double)`). Since the

    /// struct has no captures it never changes, so it's built once by the shared

    /// `start` function instead of being reconstructed per reference.

    pub named_fn_values: HashMap<String, u32>,

    /// Shared runtime helper `(a: ref Str, b: ref Str) -> ref Str`: allocates a new

    /// `array<i8>` exactly long enough to hold `a`'s bytes followed by `b`'s, for

    /// lowering string interpolation (`"{expr}"`).

    pub string_concat_func: u32,

    /// Shared runtime helper `(n: i64) -> ref Str`: allocates a new `array<i8>`

    /// holding `n`'s decimal representation, for interpolating an `Int`.

    pub int_to_string_func: u32,

    /// wasm-gc type-section indices for this program's classes/enums/Str/closures —

    /// every value's real representation (see `docs/superpowers/plans/2026-07-25-wasm-gc-migration.md`).

    pub gc_types: GcTypeRegistry,

    /// Payload-free variant name (True/False/None/...) -> the global index holding

    /// its one pre-allocated instance (see this migration plan's Decision 2).

    pub singleton_globals: HashMap<String, u32>,

}

/// Per-module state that accumulates as function bodies are compiled: every static

/// string literal's bytes, staged here (rather than added straight to `WasmModule`)

/// so `compileStaticString` can know a segment's final passive-data-section index —

/// its position among ALL staged segments — before that section is actually

/// assembled at the end of `compileSource`.

struct ModuleState {

    passive_segments: Vec<Vec<u8>>,

}

struct LocalCtx<'a> {

    locals: HashMap<String, u32>,

    /// First local index reserved for `match` subject scratch temporaries.

    match_scratch_base: u32,

    /// `Match` stmt identity (pointer address) -> scratch slot offset.

    match_scratch_index: HashMap<usize, u32>,

    /// First local index reserved for nested-constructor-pattern scratch temporaries

    /// (`Some(Some(v))`'s inner `Some(v)`); the outermost pattern uses a

    /// `match_scratch` slot instead, so this only covers depth >= 1.

    nested_class_scratch_base: u32,

    /// `CasePattern::Class` identity (pointer address) -> scratch slot offset.

    nested_class_scratch: HashMap<usize, u32>,

    /// First local index reserved for variadic-`for` scratch temporaries (2 `i32`

    /// slots per `for` statement that iterates a `TVariadic`: count, loop index).

    variadic_for_scratch_base: u32,

    /// `For` stmt identity (pointer address) -> slot number (multiply by 2 and add

    /// `variadic_for_scratch_base` for the count local; +1 more for the index local).

    variadic_for_scratch: HashMap<usize, u32>,

    func_ids: &'a HashMap<String, u32>,

    func_sigs: &'a HashMap<String, FuncSig>,

    closures: &'a HashMap<usize, ClosureInfo>,

    closure_call_types: &'a HashMap<ClosureSigKey, u32>,

    named_fn_values: &'a HashMap<String, u32>,

    string_concat_func: u32,

    int_to_string_func: u32,

    classes: &'a ClassEnv,

    methods: &'a MethodEnv,

    enum_variants: &'a EnumVariants,

    enum_params: &'a EnumParams,

    gc_types: &'a GcTypeRegistry,

    singleton_globals: &'a HashMap<String, u32>,

    /// Tracks each binding's inferred type as compilation proceeds through

    /// statements in order, mirroring `plum-checker`'s own env evolution — needed

    /// to resolve `Attribute`/`ClassCall` targets and pick the right load/store width.

    type_env: RefCell<TypeEnv>,

    /// Local name -> the exact wasm `call_indirect` signature of the closure literal

    /// assigned to it (populated when compiling that `Stmt::Assign`, straight from

    /// the already-correct `ClosureInfo` the discovery pass computed). Exists so

    /// `compileClosureCall` doesn't have to re-derive the signature via

    /// `plum_checker::inferExpr` on the closure a second time — which, unlike the

    /// discovery pass, doesn't have `resolveClosureParamTypesFromUsage`'s fix

    /// and would fall back to its old TVar-defaults-to-Int behavior, disagreeing

    /// with the (now correct) signature the closure's body was actually compiled with.

    closure_local_sigs: RefCell<HashMap<String, ClosureSigKey>>,

}

fn fnKey(f: &ast::Fn) -> String {

    match &f.type_param {

        Some(recv) => format!("{}::{}", recv, f.name),

        None => f.name.clone(),

    }

}

/// `f`'s full wasm param signature (implicit leading receiver param included, for

/// a method) — shared by real function registration and `extern fun` import

/// registration so both compute a param list the exact same way.

fn fnWasmParamTypes(f: &ast::Fn, gc_types: &GcTypeRegistry) -> Vec<ValType> {

    let mut param_types: Vec<ValType> = Vec::new();

    if let Some(recv) = &f.type_param {

        param_types.push(astTypeToWasm(recv).unwrap_or(ValType::I32));

    }

    for p in &f.params {

        let vt = match &p.ty {

            ast::ParamType::Variadic(t) => {

                let elem_vt = astTypeToWasm(&t.name).unwrap_or(ValType::I64);

                let arr_idx = *gc_types.variadic_array_type_idx.get(&elem_vt)

                    .expect("internal codegen error: variadic array type must be pre-registered for every elem type in the program");

                gcRef(arr_idx)

            }

            other => astTypeToWasm(paramTypeName(other)).unwrap_or(ValType::I32),

        };

        param_types.push(vt);

    }

    param_types

}

fn paramTypeName(pt: &ast::ParamType) -> &str {

    match pt {

        ast::ParamType::Type(t) => t.name.as_str(),

        ast::ParamType::Variadic(t) => t.name.as_str(),

        // TODO: fn-value params aren't modeled as a wasm value type yet; treat as

        // an unmodeled type (pointer), same as a class instance.

        ast::ParamType::Fn(_, _) => "Fn",

    }

}

thread_local! {

    /// The current `compileSource` call's wasm-gc type registry. `compileSource` is

    /// the sole entry point and is never re-entrant/concurrent within one thread, so

    /// a thread-local avoids threading an explicit `&GcTypeRegistry` parameter through

    /// every one of `plumTypeToValtype`/`astTypeToWasm`'s ~25 call sites (many several

    /// functions removed from anywhere a `CompileCtx`/`LocalCtx` is in scope, e.g.

    /// function-signature registration that runs before any `LocalCtx` exists). Set

    /// once near the top of `compileSource`, before anything below reads it.

    static CURRENT_GC_TYPES: RefCell<Option<GcTypeRegistry>> = const { RefCell::new(None) };

}

thread_local! {

    /// Top-level `NAME = literal` const values, keyed by name — set once near the

    /// top of `compileSource`, alongside `CURRENT_GC_TYPES` (same non-reentrancy

    /// rationale). A bare `NAME` reference always lexes as a type_identifier (any

    /// uppercase-leading name does, there's no separate "constant" token — see

    /// `plum-checker`'s `inferExpr`'s matching `TypeName` comment), so `Expr::TypeName`

    /// consults this map before falling back to enum-variant/unmodeled-type handling.

    static CURRENT_CONSTS: RefCell<HashMap<String, ast::Expr>> = RefCell::new(HashMap::new());

}

fn withGcTypes<R>(f: impl FnOnce(&GcTypeRegistry) -> R) -> R {

    CURRENT_GC_TYPES.with(|c| {

        let borrow = c.borrow();

        let registry = borrow.as_ref().expect("internal codegen error: GC type registry read before compileSource initialized it");

        f(registry)

    })

}

/// Resolves an `ast::Type`/`ast::ParamType`'s bare name (e.g. from a function

/// signature, before any `PlumType`/checker involvement) to its wasm-gc `ValType`.

fn astTypeToWasm(name: &str) -> Option<ValType> {

    match name {

        "Int" => Some(ValType::I64),

        "Float" => Some(ValType::F64),

        "Unit" => None,

        "Bool" => Some(plumTypeToValtype(&PlumType::TBool)),

        "Str" => Some(plumTypeToValtype(&PlumType::TStr)),

        "Byte" => Some(plumTypeToValtype(&PlumType::TByte)),

        "[]Byte" => Some(plumTypeToValtype(&PlumType::TByteSlice)),

        // "ByteSlice" (as opposed to "[]Byte") is never written in source as a type

        // annotation — it's `methodReceiverName`'s name for `TByteSlice`, which is

        // how a `ByteSlice` method's `self` param and any `ByteSlice.foo(...)`

        // static-call receiver slot get resolved here (see `fnWasmParamTypes` and

        // the `is_static_call` site). Without this arm it would fall through to the

        // generic `TNamed` branch below and get treated as an ordinary (and, for

        // this name, orphaned/unused) class struct type instead of the shared

        // `array<i8>` ref every `[]Byte` value actually is.

        "ByteSlice" => Some(plumTypeToValtype(&PlumType::TByteSlice)),

        other => Some(plumTypeToValtype(&PlumType::TNamed(other.to_string()))),

    }

}

/// A `ref null $Ty` — every heap value (class instance, enum/Bool variant, Str

/// array, closure struct) is nullable-by-convention, matching how a bump-allocator

/// i32 pointer could be "null" (0) too; nothing in this codegen currently relies on

/// non-nullable refs for an optimization, so nullable everywhere keeps this simple.

fn gcRef(idx: u32) -> ValType {

    ValType::Ref(RefType { nullable: true, heap_type: HeapType::Concrete(idx) })

}

/// Pushes an arbitrary value of the right wasm type for a "self" slot nothing

/// will ever actually read — see the `is_static_call` case in `Expr::Attribute`'s

/// `AttrKind::Method` codegen. A GC ref's null is exactly as good as a real

/// instance when the callee's body has no `self` binding to dereference it with.

fn pushSelfPlaceholder(vt: ValType, body: &mut Vec<u8>) {

    match vt {

        ValType::I64 => Instruction::I64Const(0).encode(body),

        ValType::I32 => Instruction::I32Const(0).encode(body),

        ValType::F64 => Instruction::F64Const(0.0).encode(body),

        ValType::F32 => Instruction::F32Const(0.0).encode(body),

        ValType::Ref(rt) => Instruction::RefNull(rt.heap_type).encode(body),

        ValType::V128 => Instruction::V128Const(0).encode(body),

    }

}

fn plumTypeToValtype(t: &PlumType) -> ValType {

    match t {

        PlumType::TInt => ValType::I64,

        PlumType::TFloat => ValType::F64,

        PlumType::TBool => withGcTypes(|r| gcRef(*r.enum_super_type_idx.get("Bool").expect("Bool must be registered"))),

        PlumType::TStr => withGcTypes(|r| gcRef(r.str_type_idx)),

        PlumType::TByte => ValType::I32,

        // `[]Byte` is represented by the EXACT SAME wasm-gc array type as `Str`

        // (a mutable `array<i8>`) — they're structurally identical, and nothing

        // in this codegen needs to distinguish them at the wasm-type level

        // (no runtime `ref.test`/dynamic dispatch keys off it), so reusing

        // `str_type_idx` avoids a second, redundant GC type-section entry.

        PlumType::TByteSlice => withGcTypes(|r| gcRef(r.str_type_idx)),

        PlumType::TNamed(name) => withGcTypes(|r| {

            match r.class_type_idx.get(name).or_else(|| r.enum_super_type_idx.get(name)) {

                Some(idx) => gcRef(*idx),

                // Genuinely unmodeled type name (not a real class/enum) — permissive

                // fallback, matching this function's pre-wasm-gc "unmodeled type:

                // pointer" behavior; codegen sites that actually need a concrete

                // struct type still resolve it themselves and error clearly if absent.

                None => ValType::Ref(RefType::ANYREF),

            }

        }),

        // A closure value is a 2-field `{table_index: i32, env: anyref}` struct —

        // its OWN concrete GC type, registered per Task 2e (closures), not through

        // this general resolver; `anyref` here is a safe placeholder used only

        // where a closure's exact struct type isn't being constructed/destructured

        // directly (e.g. deciding a local's storage class), matching `TVariadic`'s

        // existing "not modeled as a concrete shape here" treatment.

        PlumType::TFun(_, _) | PlumType::TVariadic(_) => ValType::Ref(RefType::ANYREF),

        PlumType::TVar(_) | PlumType::TUnit => ValType::I64,

    }

}

/// Type-section indices for every wasm-gc composite type this program's monomorphized

/// classes/enums/`Str` need. Populated once in `compileSource` from the checker's

/// global tables.

#[derive(Clone)]

pub struct GcTypeRegistry {

    /// Concrete class/struct name -> its one wasm-gc `struct` type index.

    pub class_type_idx: HashMap<String, u32>,

    /// Enum name -> its abstract supertype `struct` type index (every variant

    /// subtypes this) — includes the built-in `Bool` enum, which has no

    /// `ast::Item::Enum` of its own (`buildGlobalTables` hardcodes its

    /// `True`/`False` variants directly into `EnumVariants`).

    pub enum_super_type_idx: HashMap<String, u32>,

    /// Variant name (flat namespace, matching `EnumVariants`) -> its concrete

    /// subtype `struct` type index.

    pub variant_type_idx: HashMap<String, u32>,

    /// The single shared `array<i8>` type index every `Str` value uses.

    pub str_type_idx: u32,

    /// The single shared closure-value struct type index — `{table_idx: i32, env:

    /// anyref}` — every closure (and zero-capture "trampoline") uses regardless of

    /// its own captures; only assigned once closures are discovered (see

    /// `compileSource`), so `0` until then (nothing reads it earlier).

    pub closure_type_idx: u32,

    /// Wasm value type -> the shared `array<T>` type index used to pass a `...T`

    /// variadic argument pack as one GC array (replacing the old bump-allocated

    /// `[count][elem...]` blob — `array.len` replaces the explicit count). Populated

    /// alongside `closure_type_idx`, from every `ParamType::Variadic` in the program.

    pub variadic_array_type_idx: HashMap<ValType, u32>,

}

/// Resolves a plum type to the wasm-gc `ValType` its values are represented as, given

/// an ALREADY fully-populated `GcTypeRegistry` — every class/enum/Str index must exist

/// before this is called, since e.g. a class field of another class's type needs that

/// other class's index to already be assigned (see `buildGcTypeRegistry`'s two-pass

/// structure: this function is only ever called during its second pass).

fn plumTypeToGcValtype(t: &PlumType, registry: &GcTypeRegistry) -> ValType {

    match t {

        PlumType::TInt => ValType::I64,

        PlumType::TFloat => ValType::F64,

        PlumType::TBool => {

            let idx = *registry.enum_super_type_idx.get("Bool").expect("internal codegen error: Bool must be registered in the GC type registry");

            ValType::Ref(RefType { nullable: true, heap_type: HeapType::Concrete(idx) })

        }

        PlumType::TStr => ValType::Ref(RefType { nullable: true, heap_type: HeapType::Concrete(registry.str_type_idx) }),

        PlumType::TByte => ValType::I32,

        // See the matching comment in `plumTypeToValtype` — `[]Byte` reuses `Str`'s

        // `array<i8>` GC type index rather than getting its own.

        PlumType::TByteSlice => ValType::Ref(RefType { nullable: true, heap_type: HeapType::Concrete(registry.str_type_idx) }),

        PlumType::TNamed(name) => match registry.class_type_idx.get(name).or_else(|| registry.enum_super_type_idx.get(name)) {

            Some(idx) => ValType::Ref(RefType { nullable: true, heap_type: HeapType::Concrete(*idx) }),

            // A field typed as a generic enum/class (e.g. `Node.next: Option[Node]`)

            // resolves here to the BARE generic name — `ClassEnv`'s `plumTypeFromAst`

            // has no representation for type arguments, so it can't know this means

            // `Option$Int` once monomorphization specializes (and removes the

            // unspecialized) `Option` — same permissive `anyref` fallback as

            // `plumTypeToValtype` above, for the same "genuinely unmodeled" reason:

            // `struct.get`/`ref.test`/`ref.cast` all work against `anyref` operands

            // fine, so a field merely being STORED as `anyref` instead of the exact

            // concrete type costs nothing but static precision.

            None => ValType::Ref(RefType::ANYREF),

        },

        // TFun (closures) and TVariadic get their own concrete representation once

        // Task 2 (closures/variadic calls) lands — `anyref` is a safe, valid-but-not-

        // yet-meaningful placeholder in the meantime, since nothing consumes it yet.

        PlumType::TFun(_, _) | PlumType::TVariadic(_) => ValType::Ref(RefType::ANYREF),

        PlumType::TVar(_) | PlumType::TUnit => ValType::I64,

    }

}

/// Builds the wasm-gc type registry for every concrete class/enum in `source`, plus

/// the built-in `Bool` enum and the shared `Str` array type, and declares them all as

/// ONE `rec` group via `module.addGcTypes` — a single group sidesteps every ordering

/// question about mutual/self-references (a class field of another class's type, an

/// enum variant field referencing its own enum, `Node.next: Option[Node]`, etc.),

/// since within one `rec` group members may reference each other regardless of

/// declaration order.

fn buildGcTypeRegistry(

    module: &mut WasmModule,

    source: &ast::Source,

    classes: &ClassEnv,

    enum_variants: &EnumVariants,

    enum_params: &EnumParams,

) -> GcTypeRegistry {

    enum Slot {

        Str,

        Class(String),

        EnumSuper(String),

        Variant(String),

    }

    // Pass 1: assign every entry a slot (and therefore a type index) up front, before

    // any field list is built, so field-type resolution can reference ANY other entry.

    let mut slots: Vec<Slot> = vec![Slot::Str];

    let mut class_type_idx: HashMap<String, u32> = HashMap::new();

    let mut enum_super_type_idx: HashMap<String, u32> = HashMap::new();

    let mut variant_type_idx: HashMap<String, u32> = HashMap::new();

    for item in &source.items {

        if let ast::Item::Class(c) = item {

            class_type_idx.insert(c.name.clone(), slots.len() as u32);

            slots.push(Slot::Class(c.name.clone()));

        }

    }

    // Bool is built into `EnumVariants` (True/False) by `buildGlobalTables` with no

    // `ast::Item::Enum` of its own (see `docs/superpowers/plans/2026-07-25-wasm-gc-migration.md`'s

    // Decision 1: Bool is a full wasm-gc struct, no special-casing) — register it

    // exactly like a real enum here, ahead of whatever the source actually declares.

    let mut enum_decls: Vec<(String, Vec<String>)> =

        vec![("Bool".to_string(), vec!["False".to_string(), "True".to_string()])];

    for item in &source.items {

        // A source file may re-"declare" `enum Bool = | True | False` purely to

        // give it a nesting site for methods (no other way exists to attach a

        // method to a builtin type) — see the identical skip, with the full

        // rationale, in `plum-checker`'s `buildGlobalTables`. Registering it

        // again here would give Bool a SECOND, orphaned GC struct (the first,

        // hardcoded one is still referenced by every OTHER already-registered

        // slot/type by index) and — worse — since slot assignment for a

        // specialized generic enum with a `Bool` field (e.g. `Result[Bool,

        // Str]`) resolves "Bool" by NAME at the point it's compiled, later

        // duplicate registrations can leave that field pointing at whichever

        // Bool slot was assigned last, an index that isn't guaranteed to

        // satisfy wasm-gc's "supertypes before subtypes" ordering rule.

        if let ast::Item::Enum(e) = item {

            if e.name != "Bool" {

                enum_decls.push((e.name.clone(), e.variants.iter().map(|v| v.name.clone()).collect()));

            }

        }

    }

    for (enum_name, variant_names) in &enum_decls {

        enum_super_type_idx.insert(enum_name.clone(), slots.len() as u32);

        slots.push(Slot::EnumSuper(enum_name.clone()));

        for vname in variant_names {

            variant_type_idx.insert(vname.clone(), slots.len() as u32);

            slots.push(Slot::Variant(vname.clone()));

        }

    }

    // The registry is fully index-complete after pass 1 (every name has an assigned

    // slot) even though no field lists exist yet — safe to hand to `plumTypeToGcValtype`

    // for pass 2's field-type resolution.

    let registry = GcTypeRegistry {

        class_type_idx,

        enum_super_type_idx,

        variant_type_idx,

        str_type_idx: 0,

        closure_type_idx: 0,

        variadic_array_type_idx: HashMap::new(),

    };

    // Pass 2: build the real SubType for every slot, now that every cross-reference

    // resolves.

    let subtypes: Vec<SubType> = slots.iter().map(|slot| match slot {

        Slot::Str => SubType {

            is_final: true,

            supertype_idx: None,

            composite_type: CompositeType {

                inner: CompositeInnerType::Array(ArrayType(FieldType { element_type: StorageType::I8, mutable: true })),

                shared: false,

            },

        },

        Slot::Class(name) => {

            let fields = classes.get(name).cloned().unwrap_or_default();

            let field_types: Vec<FieldType> = fields.iter().map(|(_, ty)| FieldType {

                element_type: StorageType::Val(plumTypeToGcValtype(ty, &registry)),

                mutable: true,

            }).collect();

            SubType {

                is_final: true,

                supertype_idx: None,

                composite_type: CompositeType { inner: CompositeInnerType::Struct(StructType { fields: field_types.into() }), shared: false },

            }

        }

        // An ORDINARY enum's supertype declares zero fields (each variant adds its

        // own distinct payload fields below it). A DISCRIMINANT enum (`enum

        // Foo(n: Int) = ...`) is different: every variant shares the EXACT SAME

        // field list (`plum-checker::buildGlobalTables` already gives every variant

        // of such an enum identical `field_types`, equal to the shared params), so

        // the supertype declares those fields directly — this is what lets `self.n`

        // field access work on the plain supertype-typed reference with a

        // `struct.get`, no `ref.cast` to one arbitrary variant required (which would

        // trap at runtime whenever `self` isn't actually THAT variant).

        Slot::EnumSuper(enum_name) => {

            let params = enum_params.get(enum_name).cloned().unwrap_or_default();

            let field_types: Vec<FieldType> = params.iter().map(|(_, ty)| FieldType {

                element_type: StorageType::Val(plumTypeToGcValtype(ty, &registry)),

                mutable: false,

            }).collect();

            SubType {

                is_final: false,

                supertype_idx: None,

                composite_type: CompositeType { inner: CompositeInnerType::Struct(StructType { fields: field_types.into() }), shared: false },

            }

        }

        Slot::Variant(vname) => {

            let info = enum_variants.get(vname)

                .unwrap_or_else(|| panic!("internal codegen error: variant '{}' missing from EnumVariants", vname));

            let super_idx = *registry.enum_super_type_idx.get(&info.enum_name)

                .unwrap_or_else(|| panic!("internal codegen error: enum '{}' missing its supertype slot", info.enum_name));

            // For a discriminant enum, `info.field_types` is ALREADY identical to the

            // supertype's own fields (see the `EnumSuper` arm above) — a variant with

            // zero ADDED fields beyond its supertype is still valid wasm-gc

            // subtyping, so no special-casing is needed here.

            let field_types: Vec<FieldType> = info.field_types.iter().map(|ty| FieldType {

                element_type: StorageType::Val(plumTypeToGcValtype(ty, &registry)),

                mutable: false,

            }).collect();

            SubType {

                is_final: true,

                supertype_idx: Some(super_idx),

                composite_type: CompositeType { inner: CompositeInnerType::Struct(StructType { fields: field_types.into() }), shared: false },

            }

        }

    }).collect();

    module.addGcTypes(subtypes);

    registry

}

/// Maps an `ast::ParamType::Fn(params, ret)` to the wasm signature of the *closure

/// function* it compiles to: an implicit leading `env: anyref`, then one param per

/// declared param type, returning `ret`'s val type (or nothing for `Unit`).

fn fnParamTypeToWasmSig(params: &[ast::Type], ret: &Option<Box<ast::Type>>) -> (Vec<ValType>, Option<ValType>) {

    let mut vts = vec![ValType::Ref(RefType::ANYREF)]; // env pointer

    for p in params {

        vts.push(astTypeToWasm(&p.name).unwrap_or(ValType::I32));

    }

    let ret_vt = ret.as_ref().and_then(|t| astTypeToWasm(&t.name));

    (vts, ret_vt)

}

fn blockTypeFor(result_vt: Option<ValType>) -> BlockType {

    result_vt.map(BlockType::Result).unwrap_or(BlockType::Empty)

}

fn retTypeToWasm(ret: Option<&ast::Type>) -> Option<ValType> {

    ret.and_then(|r| astTypeToWasm(&r.name))

}

fn encodeLeb128U32(mut val: u32) -> Vec<u8> {

    let mut bytes = Vec::new();

    loop {

        let mut byte = (val & 0x7f) as u8;

        val >>= 7;

        if val != 0 {

            byte |= 0x80;

        }

        bytes.push(byte);

        if val == 0 {

            break;

        }

    }

    bytes

}

fn checkCtxOf<'a>(ctx_classes: &'a ClassEnv, ctx_methods: &'a MethodEnv, ctx_enum_variants: &'a EnumVariants, ctx_enum_params: &'a EnumParams) -> plum_checker::CheckCtx<'a> {

    plum_checker::CheckCtx { classes: ctx_classes, methods: ctx_methods, enum_variants: ctx_enum_variants, enum_params: ctx_enum_params }

}

/// Infers an expression's type using the function's current (mutable, evolving) type

/// environment. Defaults to `TInt` if inference fails — codegen assumes the source was

/// already accepted by `plum_checker::checkSource`, so a failure here would indicate

/// codegen is being driven directly on unchecked input (as some tests do).

fn inferLocalType(expr: &ast::Expr, ctx: &LocalCtx) -> PlumType {

    let env = ctx.type_env.borrow();

    let cctx = checkCtxOf(ctx.classes, ctx.methods, ctx.enum_variants, ctx.enum_params);

    plum_checker::inferExpr(expr, &env, &cctx).unwrap_or(PlumType::TInt)

}

pub fn compileSource(source: &ast::Source) -> Result<Vec<u8>, String> {

    let source = &plum_checker::monomorphize::monomorphizeSource(source)?;

    let (global_env, classes, methods, enum_variants, enum_params) = plum_checker::buildGlobalTables(source);

    let mut module = WasmModule::new();

    let mut gc_types = buildGcTypeRegistry(&mut module, source, &classes, &enum_variants, &enum_params);

    CURRENT_GC_TYPES.with(|c| *c.borrow_mut() = Some(gc_types.clone()));

    CURRENT_CONSTS.with(|c| {

        let mut consts = c.borrow_mut();

        for item in &source.items {

            if let ast::Item::Const(cst) = item {

                consts.insert(cst.name.clone(), cst.value.clone());

            }

        }

    });

    // Register one shared `array<T>` GC type per distinct wasm value type used by a

    // `...T` variadic parameter anywhere in the program (almost always just one, e.g.

    // `Int...`) — replaces the old bump-allocated `[count][elem...]` blob (`array.len`

    // replaces the explicit count word). Must happen before function signatures are

    // registered below, since a variadic param's wasm type is this array's `ref`.

    let mut variadic_elem_vts: Vec<ValType> = Vec::new();

    for item in &source.items {

        if let ast::Item::Fn(f) = item {

            for p in &f.params {

                if let ast::ParamType::Variadic(t) = &p.ty {

                    let vt = astTypeToWasm(&t.name).unwrap_or(ValType::I64);

                    if !variadic_elem_vts.contains(&vt) {

                        variadic_elem_vts.push(vt);

                    }

                }

            }

        }

    }

    let variadic_array_subtypes: Vec<SubType> = variadic_elem_vts.iter().map(|vt| SubType {

        is_final: true,

        supertype_idx: None,

        composite_type: CompositeType {

            inner: CompositeInnerType::Array(ArrayType(FieldType { element_type: StorageType::Val(*vt), mutable: false })),

            shared: false,

        },

    }).collect();

    if !variadic_array_subtypes.is_empty() {

        let indices = module.addGcTypes(variadic_array_subtypes);

        for (vt, idx) in variadic_elem_vts.iter().zip(indices) {

            gc_types.variadic_array_type_idx.insert(*vt, idx);

        }

        CURRENT_GC_TYPES.with(|c| *c.borrow_mut() = Some(gc_types.clone()));

    }

    // Register every `extern fun` (e.g. `libs/std/os.plum`'s `printLn`) as a

    // genuine wasm import BEFORE any function (including the `start` function

    // set up right below) — imports must occupy the low end of the function

    // index space for every later `addFunction`'s index arithmetic to stay

    // correct. `plum-checker` has already confirmed every extern fn has no

    // receiver and no body, so `f.name` alone (no `fnKey` receiver-mangling) is

    // always its unique key.

    let mut func_ids: HashMap<String, u32> = HashMap::new();

    let mut func_sigs: HashMap<String, FuncSig> = HashMap::new();

    for item in &source.items {

        if let ast::Item::Fn(f) = item {

            if !f.is_extern {

                continue;

            }

            let param_types = fnWasmParamTypes(f, &gc_types);

            let ret = retTypeToWasm(f.returns.as_ref());

            let results_vec: Vec<ValType> = ret.into_iter().collect();

            let type_idx = module.addType(&param_types, &results_vec);

            let func_idx = module.addImport("plum", &f.name, type_idx);

            func_ids.insert(f.name.clone(), func_idx);

            func_sigs.insert(f.name.clone(), FuncSig { params: param_types, ret });

        }

    }

    // Pre-allocate one instance of every payload-free variant (True/False/None/...)

    // as a global, populated once by a `start` function rather than reconstructed on

    // every reference — see this migration plan's Decision 2. `struct.new` isn't

    // allowed inside a global's own const-expr initializer (confirmed empirically in

    // Task 1), so each global starts `ref.null` and a `start` function fills it in

    // before any export is callable. The zero-capture "trampoline" closures

    // registered below (once closures are discovered) append to this SAME start

    // function, so its body isn't finalized/patched into the module until then.

    let mut singleton_globals: HashMap<String, u32> = HashMap::new();

    let mut start_body = Vec::new();

    for (name, info) in &enum_variants {

        if !info.field_types.is_empty() {

            continue;

        }

        let variant_idx = *gc_types.variant_type_idx.get(name)

            .unwrap_or_else(|| panic!("internal codegen error: payload-free variant '{}' missing from GC type registry", name));

        let mut init = Vec::new();

        Instruction::RefNull(HeapType::Concrete(variant_idx)).encode(&mut init);

        let global_idx = module.addGlobal(gcRef(variant_idx), true, &init);

        singleton_globals.insert(name.clone(), global_idx);

        Instruction::StructNewDefault(variant_idx).encode(&mut start_body);

        Instruction::GlobalSet(global_idx).encode(&mut start_body);

    }

    let start_type_idx = module.addType(&[], &[]);

    let start_func_idx = module.addFunction(start_type_idx, &[]);

    module.setStartFunction(start_func_idx);

    // Closure wasm signature -> function-type index, deduped so every closure/call site

    // of the same shape shares one `call_indirect` type.

    let mut closure_call_types: HashMap<ClosureSigKey, u32> = HashMap::new();

    // Register every function AND method signature up front (methods get an implicit

    // leading `self: pointer` param and are keyed as "Receiver::method").

    for item in &source.items {

        if let ast::Item::Fn(f) = item {

            if f.is_extern {

                continue;

            }

            let param_types = fnWasmParamTypes(f, &gc_types);

            let ret = retTypeToWasm(f.returns.as_ref());

            let results_vec: Vec<ValType> = ret.into_iter().collect();

            let type_idx = module.addType(&param_types, &results_vec);

            let func_idx = module.addFunction(type_idx, &[]);

            let key = fnKey(f);

            func_ids.insert(key.clone(), func_idx);

            func_sigs.insert(key, FuncSig { params: param_types, ret });

            // Any `fn(...) -> ...`-typed param is callable via `call_indirect`; register

            // its wasm signature (leading env-ptr param included) so call sites can

            // resolve a consistent type index even if no matching closure literal exists.

            for p in &f.params {

                if let ast::ParamType::Fn(params, ret) = &p.ty {

                    let (sig_params, ret_vt) = fnParamTypeToWasmSig(params, ret);

                    let sig_key: ClosureSigKey = (sig_params.clone(), ret_vt);

                    if !closure_call_types.contains_key(&sig_key) {

                        let results: Vec<ValType> = ret_vt.into_iter().collect();

                        let tidx = module.addType(&sig_params, &results);

                        closure_call_types.insert(sig_key, tidx);

                    }

                }

            }

        }

    }

    let fns: Vec<&ast::Fn> = source.items.iter().filter_map(|item| match item {

        ast::Item::Fn(f) if !f.is_extern => Some(f),

        _ => None,

    }).collect();

    // ---- Discovery pre-pass: find every closure literal in every function body. ----

    // (Runs on the monomorphized source, so any generic types in a closure's context

    // are already concrete.) Registers each closure as its own wasm function + table

    // element and records the free variables it must capture.

    let fn_decls: HashMap<String, &ast::Fn> = fns.iter().map(|f| (f.name.clone(), *f)).collect();

    let mut raw_closures: Vec<RawClosure> = Vec::new();

    let mut named_fn_refs: HashSet<String> = HashSet::new();

    for f in &fns {

        let mut env = global_env.clone();

        if let Some(recv) = &f.type_param {

            env.insert("self".to_string(), TypeScheme::mono(plum_checker::plumTypeFromName(recv)));

        }

        let mut locals: HashSet<String> = HashSet::new();

        for p in &f.params {

            env.insert(p.name.clone(), TypeScheme::mono(paramPlumType(&p.ty)));

            locals.insert(p.name.clone());

        }

        let mut walker = ClosureWalker {

            env,

            cctx: checkCtxOf(&classes, &methods, &enum_variants, &enum_params),

            fn_decls: &fn_decls,

            found: Vec::new(),

            locals,

            named_fn_refs: HashSet::new(),

        };

        match &f.body {

            ast::FnBody::Block(block) => walker.walkBlock(block),

            ast::FnBody::Expr(e) => walker.walkExpr(e, None),

            // `fns` excludes every `extern fun` (no body to discover closures in).

            ast::FnBody::Extern => unreachable!("extern fns are excluded from `fns`"),

        }

        raw_closures.extend(walker.found);

        named_fn_refs.extend(walker.named_fn_refs);

    }

    // Register every closure literal's own env struct type, plus the ONE shared

    // closure-value struct `{table_idx: i32, env: anyref}` every closure (and

    // trampoline, below) wraps its env in — declared together as a single `rec`

    // group now that every closure's free-variable types are known. The shared

    // struct is always slot 0; closure `i`'s env type is slot `i + 1`.

    let mut closure_subtypes: Vec<SubType> = vec![SubType {

        is_final: true,

        supertype_idx: None,

        composite_type: CompositeType {

            inner: CompositeInnerType::Struct(StructType {

                fields: vec![

                    FieldType { element_type: StorageType::Val(ValType::I32), mutable: false },

                    FieldType { element_type: StorageType::Val(ValType::Ref(RefType::ANYREF)), mutable: false },

                ].into(),

            }),

            shared: false,

        },

    }];

    for rc in &raw_closures {

        let field_types: Vec<FieldType> = rc.free_vars.iter().map(|(_, ty)| FieldType {

            element_type: StorageType::Val(plumTypeToValtype(ty)),

            mutable: false,

        }).collect();

        closure_subtypes.push(SubType {

            is_final: true,

            supertype_idx: None,

            composite_type: CompositeType { inner: CompositeInnerType::Struct(StructType { fields: field_types.into() }), shared: false },

        });

    }

    let closure_type_indices = module.addGcTypes(closure_subtypes);

    gc_types.closure_type_idx = closure_type_indices[0];

    CURRENT_GC_TYPES.with(|c| *c.borrow_mut() = Some(gc_types.clone()));

    let mut closures: HashMap<usize, ClosureInfo> = HashMap::new();

    let mut closure_asts: HashMap<usize, &ast::Closure> = HashMap::new();

    for (i, rc) in raw_closures.iter().enumerate() {

        let mut sig_params = vec![ValType::Ref(RefType::ANYREF)]; // env pointer

        sig_params.extend(rc.param_vts.iter().copied());

        let sig_key: ClosureSigKey = (sig_params.clone(), rc.ret_vt);

        let type_idx = match closure_call_types.get(&sig_key) {

            Some(t) => *t,

            None => {

                let results: Vec<ValType> = rc.ret_vt.into_iter().collect();

                let t = module.addType(&sig_params, &results);

                closure_call_types.insert(sig_key, t);

                t

            }

        };

        let func_idx = module.addFunction(type_idx, &[]);

        let table_idx = module.addTableElement(func_idx);

        closures.insert(rc.ptr, ClosureInfo {

            func_idx,

            table_idx,

            env_type_idx: closure_type_indices[i + 1],

            param_vts: rc.param_vts.clone(),

            param_ptypes: rc.param_ptypes.clone(),

            ret_vt: rc.ret_vt,

            free_vars: rc.free_vars.clone(),

        });

        closure_asts.insert(rc.ptr, rc.closure);

    }

    // Register a zero-capture "trampoline" closure for every top-level function

    // referenced as a bare value (e.g. `each(double)`): a real wasm function with the

    // closure calling convention `(env, ...real_params) -> ret` that ignores its env

    // and forwards straight to the real function, plus a funcref-table entry for it.

    // Since it never captures anything, its `{table_idx, env=null}` closure struct is

    // a compile-time constant — like every payload-free enum variant, built once by

    // the shared `start` function and stored in its own global.

    let mut named_fn_values: HashMap<String, u32> = HashMap::new();

    for name in &named_fn_refs {

        let sig = func_sigs.get(name).expect("named fn ref must be a registered top-level function");

        let real_func_idx = *func_ids.get(name).expect("named fn ref must be a registered top-level function");

        let mut sig_params = vec![ValType::Ref(RefType::ANYREF)]; // env pointer

        sig_params.extend(sig.params.iter().copied());

        let sig_key: ClosureSigKey = (sig_params.clone(), sig.ret);

        let type_idx = match closure_call_types.get(&sig_key) {

            Some(t) => *t,

            None => {

                let results: Vec<ValType> = sig.ret.into_iter().collect();

                let t = module.addType(&sig_params, &results);

                closure_call_types.insert(sig_key, t);

                t

            }

        };

        let mut tbody = Vec::new();

        tbody.push(0u8); // no locals beyond the params already in the signature

        for i in 0..sig.params.len() {

            Instruction::LocalGet((i + 1) as u32).encode(&mut tbody); // local 0 is env, ignored

        }

        Instruction::Call(real_func_idx).encode(&mut tbody);

        Instruction::End.encode(&mut tbody);

        let func_idx = module.addFunction(type_idx, &tbody);

        let table_idx = module.addTableElement(func_idx);

        let mut init = Vec::new();

        Instruction::RefNull(HeapType::Concrete(gc_types.closure_type_idx)).encode(&mut init);

        let global_idx = module.addGlobal(gcRef(gc_types.closure_type_idx), true, &init);

        named_fn_values.insert(name.clone(), global_idx);

        Instruction::I32Const(table_idx as i32).encode(&mut start_body);

        Instruction::RefNull(HeapType::ANY).encode(&mut start_body);

        Instruction::StructNew(gc_types.closure_type_idx).encode(&mut start_body);

        Instruction::GlobalSet(global_idx).encode(&mut start_body);

    }

    // The `start` function is now complete — every payload-free variant singleton

    // (above) and every trampoline closure (above) has appended its own init code.

    // It declares no locals of its own, but a function body's raw bytes must still

    // start with the (empty) locals-declaration vector — a single `0x00` — before

    // the instruction stream, exactly like every other compiled function body below.

    Instruction::End.encode(&mut start_body);

    let mut final_start_body = vec![0u8];

    final_start_body.extend(start_body);

    let start_slot = (start_func_idx - module.func_import_count) as usize;

    module.functions[start_slot].1 = final_start_body;

    // Runtime helpers backing string interpolation (`"{expr}"`): always registered

    // (unconditionally, for simplicity) since they're cheap and self-contained.

    let string_concat_func = registerStringConcatHelper(&mut module, gc_types.str_type_idx);

    let int_to_string_func = registerIntToStringHelper(&mut module, gc_types.str_type_idx);

    let ctx = CompileCtx {

        func_ids, func_sigs, classes, methods, enum_variants, enum_params, global_env,

        closures, closure_asts, closure_call_types, named_fn_values,

        string_concat_func, int_to_string_func, gc_types, singleton_globals,

    };

    let mut state = ModuleState { passive_segments: Vec::new() };

    let mut compiled_bodies: Vec<(String, Vec<u8>)> = Vec::new();

    for f in &fns {

        let body = match compileIntrinsicFnBody(f) {

            Some(body) => body,

            None => compileFnBody(f, &ctx, &mut state)?,

        };

        compiled_bodies.push((fnKey(f), body));

    }

    // Patch compiled bodies back into their pre-registered function slots.

    for (name, body) in &compiled_bodies {

        let idx = *ctx.func_ids.get(name).expect("function was registered in the first pass");

        let slot = (idx - module.func_import_count) as usize;

        module.functions[slot].1 = body.clone();

    }

    // Compile each closure literal's own body into its reserved function slot.

    let mut closure_bodies: Vec<(u32, Vec<u8>)> = Vec::new();

    for (ptr, info) in &ctx.closures {

        let cl = ctx.closure_asts.get(ptr).expect("every registered closure has its AST recorded");

        let body = compileClosureBody(cl, info, &ctx, &mut state)?;

        closure_bodies.push((info.func_idx, body));

    }

    for (func_idx, body) in &closure_bodies {

        let slot = (*func_idx - module.func_import_count) as usize;

        module.functions[slot].1 = body.clone();

    }

    // Flush every staged string literal into the module in the SAME order they were

    // staged — `compileStaticString` already baked each one's index (its position in

    // `state.passive_segments` at staging time) into an `array.new_data` instruction,

    // so that order must be preserved exactly for those indices to still be correct.

    for bytes in &state.passive_segments {

        module.addPassiveDataSegment(bytes);

    }

    if let Some(&main_idx) = ctx.func_ids.get("main") {

        module.addExport("main", ExportKind::Func, main_idx);

    }

    Ok(module.finish())

}

/// Registers `__string_concat(a: ref Str, b: ref Str) -> ref Str`, a hand-written

/// runtime helper backing string interpolation. `Str` is a wasm-gc `array<i8>`,

/// which tracks its own length (`array.len`) — building the concatenation is:

/// allocate a new array sized `len(a) + len(b)`, then two `array.copy`s (a

/// whole-array-in-one-instruction bulk copy).

fn registerStringConcatHelper(module: &mut WasmModule, str_type_idx: u32) -> u32 {

    let str_ref = gcRef(str_type_idx);

    let type_idx = module.addType(&[str_ref, str_ref], &[str_ref]);

    // locals: 0=a (param), 1=b (param), 2=len_a, 3=len_b, 4=result

    const A: u32 = 0;

    const B: u32 = 1;

    const LEN_A: u32 = 2;

    const LEN_B: u32 = 3;

    const RESULT: u32 = 4;

    let mut body = Vec::new();

    body.extend(encodeLeb128U32(2)); // two locals groups

    body.extend(encodeLeb128U32(2)); // len_a, len_b: i32

    ValType::I32.encode(&mut body);

    body.extend(encodeLeb128U32(1)); // result: ref

    str_ref.encode(&mut body);

    // len_a = array.len(a); len_b = array.len(b)

    Instruction::LocalGet(A).encode(&mut body);

    Instruction::ArrayLen.encode(&mut body);

    Instruction::LocalSet(LEN_A).encode(&mut body);

    Instruction::LocalGet(B).encode(&mut body);

    Instruction::ArrayLen.encode(&mut body);

    Instruction::LocalSet(LEN_B).encode(&mut body);

    // result = array.new_default(str_type_idx, len_a + len_b)

    Instruction::LocalGet(LEN_A).encode(&mut body);

    Instruction::LocalGet(LEN_B).encode(&mut body);

    Instruction::I32Add.encode(&mut body);

    Instruction::ArrayNewDefault(str_type_idx).encode(&mut body);

    Instruction::LocalSet(RESULT).encode(&mut body);

    // array.copy(dst: result, dst_offset: 0, src: a, src_offset: 0, len: len_a)

    Instruction::LocalGet(RESULT).encode(&mut body);

    Instruction::I32Const(0).encode(&mut body);

    Instruction::LocalGet(A).encode(&mut body);

    Instruction::I32Const(0).encode(&mut body);

    Instruction::LocalGet(LEN_A).encode(&mut body);

    Instruction::ArrayCopy { array_type_index_dst: str_type_idx, array_type_index_src: str_type_idx }.encode(&mut body);

    // array.copy(dst: result, dst_offset: len_a, src: b, src_offset: 0, len: len_b)

    Instruction::LocalGet(RESULT).encode(&mut body);

    Instruction::LocalGet(LEN_A).encode(&mut body);

    Instruction::LocalGet(B).encode(&mut body);

    Instruction::I32Const(0).encode(&mut body);

    Instruction::LocalGet(LEN_B).encode(&mut body);

    Instruction::ArrayCopy { array_type_index_dst: str_type_idx, array_type_index_src: str_type_idx }.encode(&mut body);

    Instruction::LocalGet(RESULT).encode(&mut body);

    Instruction::End.encode(&mut body);

    module.addFunction(type_idx, &body)

}

/// Registers `__int_to_string(n: i64) -> ref Str`, a hand-written runtime helper

/// backing string interpolation: allocates a new `array<i8>` holding `n`'s decimal

/// representation (handling a leading `-` for negatives, and `0` correctly via a

/// do-while digit count that always runs at least once).

fn registerIntToStringHelper(module: &mut WasmModule, str_type_idx: u32) -> u32 {

    let str_ref = gcRef(str_type_idx);

    let type_idx = module.addType(&[ValType::I64], &[str_ref]);

    // locals: 0=n (param, i64), 1=is_neg (i32), 2=count (i32), 3=total_len (i32),

    // 4=pos (i32), 5=result (ref), 6=abs_n (i64), 7=temp (i64)

    // Locals are declared as one group of 4 `i32`s, one group of 1 `ref`, then one

    // group of 2 `i64`s (see below), so indices must stay grouped by type in that

    // same order — NOT in whatever order reads best logically.

    const N: u32 = 0;

    const IS_NEG: u32 = 1;

    const COUNT: u32 = 2;

    const TOTAL_LEN: u32 = 3;

    const POS: u32 = 4;

    const RESULT: u32 = 5;

    const ABS_N: u32 = 6;

    const TEMP: u32 = 7;

    let mut body = Vec::new();

    body.extend(encodeLeb128U32(3)); // three locals groups

    body.extend(encodeLeb128U32(4)); // is_neg, count, total_len, pos: i32

    ValType::I32.encode(&mut body);

    body.extend(encodeLeb128U32(1)); // result: ref

    str_ref.encode(&mut body);

    body.extend(encodeLeb128U32(2)); // abs_n, temp: i64

    ValType::I64.encode(&mut body);

    // is_neg = n < 0

    Instruction::LocalGet(N).encode(&mut body);

    Instruction::I64Const(0).encode(&mut body);

    Instruction::I64LtS.encode(&mut body);

    Instruction::LocalSet(IS_NEG).encode(&mut body);

    // abs_n = is_neg ? (0 - n) : n

    Instruction::LocalGet(IS_NEG).encode(&mut body);

    Instruction::If(BlockType::Result(ValType::I64)).encode(&mut body);

    Instruction::I64Const(0).encode(&mut body);

    Instruction::LocalGet(N).encode(&mut body);

    Instruction::I64Sub.encode(&mut body);

    Instruction::Else.encode(&mut body);

    Instruction::LocalGet(N).encode(&mut body);

    Instruction::End.encode(&mut body);

    Instruction::LocalSet(ABS_N).encode(&mut body);

    // count digits: do { temp /= 10; count++ } while (temp != 0); temp starts as abs_n

    Instruction::I32Const(0).encode(&mut body);

    Instruction::LocalSet(COUNT).encode(&mut body);

    Instruction::LocalGet(ABS_N).encode(&mut body);

    Instruction::LocalSet(TEMP).encode(&mut body);

    Instruction::Loop(BlockType::Empty).encode(&mut body);

    Instruction::LocalGet(TEMP).encode(&mut body);

    Instruction::I64Const(10).encode(&mut body);

    Instruction::I64DivS.encode(&mut body);

    Instruction::LocalSet(TEMP).encode(&mut body);

    Instruction::LocalGet(COUNT).encode(&mut body);

    Instruction::I32Const(1).encode(&mut body);

    Instruction::I32Add.encode(&mut body);

    Instruction::LocalSet(COUNT).encode(&mut body);

    Instruction::LocalGet(TEMP).encode(&mut body);

    Instruction::I64Const(0).encode(&mut body);

    Instruction::I64Ne.encode(&mut body);

    Instruction::BrIf(0).encode(&mut body);

    Instruction::End.encode(&mut body);

    // total_len = count + is_neg

    Instruction::LocalGet(COUNT).encode(&mut body);

    Instruction::LocalGet(IS_NEG).encode(&mut body);

    Instruction::I32Add.encode(&mut body);

    Instruction::LocalSet(TOTAL_LEN).encode(&mut body);

    // result = array.new_default(str_type_idx, total_len) — no length prefix needed,

    // `array.len` reads it back natively.

    Instruction::LocalGet(TOTAL_LEN).encode(&mut body);

    Instruction::ArrayNewDefault(str_type_idx).encode(&mut body);

    Instruction::LocalSet(RESULT).encode(&mut body);

    // pos = total_len; temp = abs_n

    Instruction::LocalGet(TOTAL_LEN).encode(&mut body);

    Instruction::LocalSet(POS).encode(&mut body);

    Instruction::LocalGet(ABS_N).encode(&mut body);

    Instruction::LocalSet(TEMP).encode(&mut body);