plum

# Generics Monomorphization Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Make user-declared generics (classes, free functions, methods on generic classes, and enums, using the currently-documented single-lowercase-letter generic syntax) actually monomorphize and compile to wasm, by specializing a mangled, fully-concrete copy of each generic item per unique concrete-type-argument combination actually used in the program, then running each specialized copy through the existing, unmodified non-generic checker/codegen pipeline.

**Architecture:** A new pass, `plum_checker::monomorphize::monomorphize_source`, runs on the raw `ast::Source` *before* both `check_source` and `compile_source` do anything else. It: (1) classifies every top-level item as generic-template (dropped from the output) or concrete (passed through, with its body rewritten in place); (2) walks every concrete function/method body with a lightweight, type-inference-driven expression rewriter that resolves each generic-construction/generic-call site's concrete type arguments (reusing `plum_checker`'s existing `infer_expr`/`unify`), mangles a specialization name, rewrites the call site to reference it, and enqueues that specialization if not already produced; (3) drains that worklist to a fixed point (a freshly-specialized body can itself introduce further, now-fully-concrete instantiation sites), guarded against runaway recursion. The output is a plain, fully-concrete `ast::Source` with zero generic syntax left in it — `plum-checker`'s and `plum-wasm-codegen`'s existing pipelines need **no changes** to consume it.

**Tech Stack:** Rust (workspace: `plum-core`, `plum-checker`, `plum-wasm-codegen`).

## Global Constraints

- **Scope of "generic" for this pass:** `Class`/`Trait` generics come from their explicit `generics: Vec<GenericParam>` list. `Fn` and `Enum` have no such list in the AST — a generic parameter is detected *implicitly*: any single-lowercase-letter type name (`a`, `b`, `c`, `d`, ...) appearing in a `Fn`'s param/return types, or an `Enum` variant's field type name, is treated as an implicit generic parameter.

- **In scope:** generic classes and their declared methods (specialized together, via the class's own substitution — a method's receiver becomes the class's mangled name); generic free functions; generic enums.

- **Out of scope (do not attempt):** a method introducing its *own* additional generic parameter beyond its receiver class's (e.g. a method-scoped `b` on top of a class-scoped `a`) — such a method is left exactly as unspecialized/permissive as it is today, matching existing behavior for a shape this pass doesn't support; trait-bound enforcement (`Comparable(a: Ord)`'s `Ord` bound) — stays permissive, unchanged; generic instantiation sites inside string-interpolation parts (string interpolation itself is a separate, already-known, unrelated codegen gap); making `libs/std/list.plum`/`map.plum` compile as-is (they need closures, `Nil`/optional-chaining, decorators, and other unimplemented syntax first — this plan does not touch the grammar or those features at all).

- Follow existing code style: terse one-line "why" comments only where non-obvious; error messages use a `"monomorphize: ..."` prefix, mirroring the existing `"codegen: ..."` convention.

- This is new algorithmic code, not a modification of existing tested logic — validate it primarily through the tests each task specifies (TDD), not by assuming any single line is exactly right on first write.

- Every task must leave `cargo test --workspace` and `npx --yes tree-sitter-cli test` (from `tooling/tree-sitter-plum/`) green before moving to the next task.

---

### Task 1: Core specialization primitives

**Files:**

- Create: `plum-checker/src/monomorphize.rs`

- Modify: `plum-checker/src/lib.rs` (add `pub mod monomorphize;`)

- Test: `plum-checker/tests/monomorphize_tests.rs` (new file)

**Interfaces:**

- Consumes: `plum_core::ast::{Class, Fn, Enum, Field, Param, ParamType, ReturnType, Type, GenericParam, EnumVariant}` (all already `Clone`); `plum_checker::types::PlumType` (already `Display`-implemented, giving `"Int"`/`"Float"`/`"Bool"`/`"Str"`/`"Unit"`/a class name for `TNamed`).

- Produces (all `pub` in `plum_checker::monomorphize`, used by Task 2 in the same file and by nothing outside this crate yet):

  ```rust

  pub fn is_generic_param_name(name: &str) -> bool

  pub fn class_generic_params(c: &ast::Class) -> Vec<String>

  pub fn fn_generic_params(f: &ast::Fn) -> Vec<String>

  pub fn enum_generic_params(e: &ast::Enum) -> Vec<String>

  pub struct Substitution(pub std::collections::BTreeMap<String, PlumType>)

  pub fn mangle(base: &str, type_args: &[PlumType]) -> String

  pub fn specialize_class(c: &ast::Class, subst: &Substitution, mangled_name: &str) -> ast::Class

  pub fn specialize_fn(f: &ast::Fn, subst: &Substitution, mangled_name: &str, new_type_param: Option<String>) -> ast::Fn

  pub fn specialize_enum(e: &ast::Enum, subst: &Substitution, mangled_name: &str) -> ast::Enum

  ```

- [ ] **Step 1: Write failing tests**

Create `plum-checker/tests/monomorphize_tests.rs`:

```rust

use plum_checker::monomorphize::*;

use plum_checker::types::PlumType;

use plum_core::ast;

#[test]

fn is_generic_param_name_accepts_single_lowercase_letters_only() {

    assert!(is_generic_param_name("a"));

    assert!(is_generic_param_name("d"));

    assert!(!is_generic_param_name("Int"));

    assert!(!is_generic_param_name("ab"));

    assert!(!is_generic_param_name("A"));

    assert!(!is_generic_param_name(""));

}

#[test]

fn class_generic_params_reads_declared_generics_list() {

    let c = ast::Class {

        name: "Box".to_string(),

        implements: vec![],

        generics: vec![ast::GenericParam { name: "a".to_string(), bounds: vec![] }],

        fields: vec![ast::Field { name: "value".to_string(), ty: ast::Type { name: "a".to_string(), generics: vec![] } }],

    };

    assert_eq!(class_generic_params(&c), vec!["a".to_string()]);

}

#[test]

fn fn_generic_params_detects_implicit_lowercase_letter_types_in_order() {

    let f = ast::Fn {

        name: "pair".to_string(),

        type_param: None,

        params: vec![

            ast::Param { name: "first".to_string(), ty: ast::ParamType::Type(ast::Type { name: "a".to_string(), generics: vec![] }), default: None },

            ast::Param { name: "second".to_string(), ty: ast::ParamType::Type(ast::Type { name: "b".to_string(), generics: vec![] }), default: None },

        ],

        returns: Some(ast::ReturnType { name: "Bool".to_string(), generics: vec![] }),

        body: ast::FnBody::Block(ast::Block { stmts: vec![] }),

    };

    assert_eq!(fn_generic_params(&f), vec!["a".to_string(), "b".to_string()]);

}

#[test]

fn enum_generic_params_detects_implicit_lowercase_letter_variant_fields() {

    let e = ast::Enum {

        name: "Option".to_string(),

        variants: vec![

            ast::EnumVariant { name: "Some".to_string(), fields: vec!["a".to_string()] },

            ast::EnumVariant { name: "None".to_string(), fields: vec![] },

        ],

    };

    assert_eq!(enum_generic_params(&e), vec!["a".to_string()]);

}

#[test]

fn mangle_joins_base_name_and_type_args() {

    assert_eq!(mangle("Box", &[PlumType::TInt]), "Box$Int");

    assert_eq!(mangle("Pair", &[PlumType::TInt, PlumType::TStr]), "Pair$Int$Str");

    assert_eq!(mangle("Green", &[]), "Green");

}

#[test]

fn specialize_class_substitutes_generic_field_types_and_clears_generics_list() {

    let c = ast::Class {

        name: "Box".to_string(),

        implements: vec![],

        generics: vec![ast::GenericParam { name: "a".to_string(), bounds: vec![] }],

        fields: vec![ast::Field { name: "value".to_string(), ty: ast::Type { name: "a".to_string(), generics: vec![] } }],

    };

    let mut bindings = std::collections::BTreeMap::new();

    bindings.insert("a".to_string(), PlumType::TInt);

    let specialized = specialize_class(&c, &Substitution(bindings), "Box$Int");

    assert_eq!(specialized.name, "Box$Int");

    assert!(specialized.generics.is_empty());

    assert_eq!(specialized.fields[0].ty.name, "Int");

}

#[test]

fn specialize_fn_substitutes_generic_param_and_return_types() {

    let f = ast::Fn {

        name: "wrap".to_string(),

        type_param: None,

        params: vec![ast::Param { name: "value".to_string(), ty: ast::ParamType::Type(ast::Type { name: "a".to_string(), generics: vec![] }), default: None }],

        returns: Some(ast::ReturnType { name: "a".to_string(), generics: vec![] }),

        body: ast::FnBody::Expr(ast::Expr::Var("value".to_string())),

    };

    let mut bindings = std::collections::BTreeMap::new();

    bindings.insert("a".to_string(), PlumType::TInt);

    let specialized = specialize_fn(&f, &Substitution(bindings), "wrap$Int", None);

    assert_eq!(specialized.name, "wrap$Int");

    match &specialized.params[0].ty {

        ast::ParamType::Type(t) => assert_eq!(t.name, "Int"),

        _ => panic!("expected ParamType::Type"),

    }

    assert_eq!(specialized.returns.unwrap().name, "Int");

}

#[test]

fn specialize_fn_sets_new_receiver_for_a_method() {

    let f = ast::Fn {

        name: "getValue".to_string(),

        type_param: Some("Box".to_string()),

        params: vec![],

        returns: Some(ast::ReturnType { name: "a".to_string(), generics: vec![] }),

        body: ast::FnBody::Expr(ast::Expr::Self_),

    };

    let mut bindings = std::collections::BTreeMap::new();

    bindings.insert("a".to_string(), PlumType::TStr);

    let specialized = specialize_fn(&f, &Substitution(bindings), "getValue", Some("Box$Str".to_string()));

    assert_eq!(specialized.name, "getValue");

    assert_eq!(specialized.type_param, Some("Box$Str".to_string()));

    assert_eq!(specialized.returns.unwrap().name, "Str");

}

#[test]

fn specialize_enum_substitutes_generic_variant_field_names() {

    let e = ast::Enum {

        name: "Option".to_string(),

        variants: vec![

            ast::EnumVariant { name: "Some".to_string(), fields: vec!["a".to_string()] },

            ast::EnumVariant { name: "None".to_string(), fields: vec![] },

        ],

    };

    let mut bindings = std::collections::BTreeMap::new();

    bindings.insert("a".to_string(), PlumType::TInt);

    let specialized = specialize_enum(&e, &Substitution(bindings), "Option$Int");

    assert_eq!(specialized.name, "Option$Int");

    assert_eq!(specialized.variants[0].fields, vec!["Int".to_string()]);

    assert!(specialized.variants[1].fields.is_empty());

}

```

- [ ] **Step 2: Run to see them fail**

Run: `cargo test -p plum-checker --test monomorphize_tests`

Expected: fails to compile — `plum_checker::monomorphize` doesn't exist yet.

- [ ] **Step 3: Create `plum-checker/src/monomorphize.rs`**

```rust

use std::collections::BTreeMap;

use plum_core::ast;

use crate::types::PlumType;

/// A single lowercase letter (`a`, `b`, `c`, `d`, ...) is the grammar's only legal

/// spelling for a generic type parameter — this is how we recognize one, since

/// `ast::Fn` and `ast::Enum` (unlike `ast::Class`/`ast::Trait`) carry no explicit

/// generics declaration list.

pub fn is_generic_param_name(name: &str) -> bool {

    let mut chars = name.chars();

    match (chars.next(), chars.next()) {

        (Some(c), None) => c.is_ascii_lowercase(),

        _ => false,

    }

}

/// The generic parameter names introduced by a `Class`, in declaration order.

pub fn class_generic_params(c: &ast::Class) -> Vec<String> {

    c.generics.iter().map(|g| g.name.clone()).collect()

}

/// The generic parameter names implicitly introduced by a `Fn` — every distinct

/// single-lowercase-letter type name appearing in its params or return type, in

/// first-appearance order.

pub fn fn_generic_params(f: &ast::Fn) -> Vec<String> {

    let mut names: Vec<String> = Vec::new();

    let mut consider = |n: &str| {

        if is_generic_param_name(n) && !names.iter().any(|x| x == n) {

            names.push(n.to_string());

        }

    };

    for p in &f.params {

        match &p.ty {

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

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

        }

    }

    if let Some(r) = &f.returns {

        consider(&r.name);

    }

    names

}

/// The generic parameter names implicitly introduced by an `Enum` — every distinct

/// single-lowercase-letter variant field type name, in first-appearance order.

pub fn enum_generic_params(e: &ast::Enum) -> Vec<String> {

    let mut names: Vec<String> = Vec::new();

    for v in &e.variants {

        for field_ty in &v.fields {

            if is_generic_param_name(field_ty) && !names.iter().any(|x| x == field_ty) {

                names.push(field_ty.clone());

            }

        }

    }

    names

}

/// A resolved binding from a generic item's parameter names to concrete types for

/// one instantiation site, e.g. `{"a": Int}` for `Box(value: 5)`.

#[derive(Debug, Clone)]

pub struct Substitution(pub BTreeMap<String, PlumType>);

impl Substitution {

    fn get(&self, name: &str) -> Option<&PlumType> {

        self.0.get(name)

    }

}

/// Converts a resolved concrete `PlumType` back into the `ast::Type` shape needed

/// to substitute into a declared field/param/return type position. Only ever

/// called with types resolved from a real call-site argument's inferred type, so

/// `TVar`/`TFun` (which never arise from a concrete argument) are an internal-error

/// case rather than something this needs to model.

fn plum_type_to_ast_type(t: &PlumType) -> ast::Type {

    let name = match t {

        PlumType::TInt => "Int".to_string(),

        PlumType::TFloat => "Float".to_string(),

        PlumType::TBool => "Bool".to_string(),

        PlumType::TStr => "Str".to_string(),

        PlumType::TUnit => "Unit".to_string(),

        PlumType::TNamed(n) => n.clone(),

        PlumType::TVar(_) | PlumType::TFun(_, _) => t.to_string(),

    };

    ast::Type { name, generics: vec![] }

}

fn substitute_type(ty: &ast::Type, subst: &Substitution) -> ast::Type {

    if ty.generics.is_empty() {

        if let Some(concrete) = subst.get(&ty.name) {

            return plum_type_to_ast_type(concrete);

        }

    }

    ast::Type {

        name: ty.name.clone(),

        generics: ty.generics.iter().map(|g| substitute_type(g, subst)).collect(),

    }

}

/// Mangles a generic item's base name and its resolved concrete type arguments

/// (in the item's own generic-parameter declaration order) into the internal name

/// used for its specialized copy, e.g. `Box` + `[Int]` -> `"Box$Int"`.

pub fn mangle(base: &str, type_args: &[PlumType]) -> String {

    let mut out = base.to_string();

    for t in type_args {

        out.push('$');

        out.push_str(&t.to_string());

    }

    out

}

/// Produces a concrete, specialized copy of a generic class under `mangled_name`,

/// substituting every field whose declared type names one of the class's generic

/// parameters with its resolved concrete type. The class's own `generics` list is

/// cleared on the copy (it is now fully concrete).

pub fn specialize_class(c: &ast::Class, subst: &Substitution, mangled_name: &str) -> ast::Class {

    ast::Class {

        name: mangled_name.to_string(),

        implements: c.implements.clone(),

        generics: vec![],

        fields: c.fields.iter().map(|f| ast::Field {

            name: f.name.clone(),

            ty: substitute_type(&f.ty, subst),

        }).collect(),

    }

}

/// Produces a concrete, specialized copy of a generic function (or method) under

/// `mangled_name`. `new_type_param` overrides the receiver-type name for a method

/// whose receiver class was itself specialized (e.g. a method declared on `Box`

/// becomes a method on `Box$Int`); pass the original `f.type_param.clone()`

/// unchanged for a plain free function. The body is left structurally identical

/// here — its own call sites are rewritten separately (Task 2), since expressions

/// don't carry declared-type annotations the way fields/params/return types do.

pub fn specialize_fn(f: &ast::Fn, subst: &Substitution, mangled_name: &str, new_type_param: Option<String>) -> ast::Fn {

    ast::Fn {

        name: mangled_name.to_string(),

        type_param: new_type_param,

        params: f.params.iter().map(|p| ast::Param {

            name: p.name.clone(),

            ty: match &p.ty {

                ast::ParamType::Type(t) => ast::ParamType::Type(substitute_type(t, subst)),

                ast::ParamType::Variadic(t) => ast::ParamType::Variadic(substitute_type(t, subst)),

            },

            default: p.default.clone(),

        }).collect(),

        returns: f.returns.as_ref().map(|r| {

            let substituted = substitute_type(&ast::Type { name: r.name.clone(), generics: vec![] }, subst);

            ast::ReturnType { name: substituted.name, generics: vec![] }

        }),

        body: f.body.clone(),

    }

}

/// Produces a concrete, specialized copy of a generic enum under `mangled_name`,

/// substituting every variant field type name that matches one of the enum's

/// generic parameters with its resolved concrete type's name.

pub fn specialize_enum(e: &ast::Enum, subst: &Substitution, mangled_name: &str) -> ast::Enum {

    ast::Enum {

        name: mangled_name.to_string(),

        variants: e.variants.iter().map(|v| ast::EnumVariant {

            name: v.name.clone(),

            fields: v.fields.iter().map(|f| {

                subst.get(f).map(|t| t.to_string()).unwrap_or_else(|| f.clone())

            }).collect(),

        }).collect(),

    }

}

```

- [ ] **Step 4: Register the module**

In `plum-checker/src/lib.rs`, add near the top (alongside the existing `pub mod types;`):

```rust

pub mod monomorphize;

```

- [ ] **Step 5: Run the tests**

Run: `cargo test -p plum-checker --test monomorphize_tests`

Expected: all 9 tests pass.

- [ ] **Step 6: Run the full checker crate suite**

Run: `cargo test -p plum-checker`

Expected: green (this new module isn't wired into `check_source` yet, so no existing behavior is affected).

- [ ] **Step 7: Commit**

```bash

git add plum-checker/src/monomorphize.rs plum-checker/src/lib.rs plum-checker/tests/monomorphize_tests.rs

git commit -m "feat(plum-checker): core generics specialization primitives"

```

---

### Task 2: Instantiation-site collection, worklist driver, and pipeline integration

**Files:**

- Modify: `plum-checker/src/monomorphize.rs` (append to the file from Task 1)

- Modify: `plum-checker/src/lib.rs` (`check_source`)

- Modify: `plum-wasm-codegen/src/lib.rs` (`compile_source`)

- Test: `plum-checker/tests/checker_tests.rs`

**Interfaces:**

- Consumes: Task 1's `class_generic_params`/`fn_generic_params`/`enum_generic_params`/`Substitution`/`mangle`/`specialize_class`/`specialize_fn`/`specialize_enum`; `plum_checker`'s existing `build_global_tables`, `infer_expr`, `unify`, `CheckCtx`, `plum_type_from_ast`, `types::{TypeEnv, TypeScheme, PlumType}`.

- Produces: `pub fn monomorphize_source(source: &ast::Source) -> Result<ast::Source, String>` — the single entry point Tasks 3 and both pipeline integrations depend on. Its output is a plain `ast::Source` containing zero generic syntax (every generic `Class`/`Fn`/`Enum` template is replaced by zero or more mangled concrete specializations, and every non-generic item's body has its call sites rewritten to reference those mangled names where needed).

- [ ] **Step 1: Write failing checker tests for the end-to-end behavior**

Append to `plum-checker/tests/checker_tests.rs`:

```rust

#[test]

fn generic_class_instantiated_at_two_concrete_types_type_checks() {

    let src = "\

type Box(a) =

  value: a

makeIntBox() -> Box =

  Box(value: 5)

makeStrBox() -> Box =

  Box(value: \"x\")

";

    let source = parse(src);

    let result = check_source(&source);

    assert!(result.is_ok(), "expected Ok, got {:?}", result.err());

}

#[test]

fn generic_function_called_with_different_concrete_types_per_site_type_checks() {

    let src = "\

wrap(value: a) -> Bool =

  True

useInt() -> Bool =

  wrap(5)

useStr() -> Bool =

  wrap(\"x\")

";

    let source = parse(src);

    let result = check_source(&source);

    assert!(result.is_ok(), "expected Ok, got {:?}", result.err());

}

#[test]

fn generic_function_with_two_independent_type_params_type_checks() {

    let src = "\

pair(first: a, second: b) -> Bool =

  True

use() -> Bool =

  pair(1, \"x\")

";

    let source = parse(src);

    let result = check_source(&source);

    assert!(result.is_ok(), "expected Ok, got {:?}", result.err());

}

#[test]

fn generic_method_on_generic_class_type_checks() {

    let src = "\

type Box(a) =

  value: a

getValue<Box>() -> a =

  self.value

use() -> Int =

  b = Box(value: 5)

  b.getValue()

";

    let source = parse(src);

    let result = check_source(&source);

    assert!(result.is_ok(), "expected Ok, got {:?}", result.err());

}

```

- [ ] **Step 2: Run to see them fail**

Run: `cargo test -p plum-checker --test checker_tests generic_`

Expected: all four fail or error, since `check_source` doesn't call `monomorphize_source` yet (a generic field/param type name like `a` is currently just permissively accepted as an unmodeled type name everywhere — these specific tests may currently happen to pass permissively too; if any already pass, note that in your report, but proceed with the implementation regardless since the goal is *correct* resolution, not merely "doesn't error").

- [ ] **Step 3: Append the `Monomorphizer` driver to `plum-checker/src/monomorphize.rs`**

```rust

use std::collections::BTreeSet;

use crate::types::{TypeEnv, TypeScheme};

use crate::{ClassEnv, MethodEnv, EnumVariants, CheckCtx};

enum PendingSpecialization<'a> {

    Class { base: &'a ast::Class, subst: Substitution, mangled: String },

    Fn { base: &'a ast::Fn, subst: Substitution, mangled: String, new_receiver: Option<String> },

    Enum { base: &'a ast::Enum, subst: Substitution, mangled: String },

}

struct Monomorphizer<'a> {

    classes_generic: BTreeMap<String, &'a ast::Class>,

    fns_generic: BTreeMap<String, &'a ast::Fn>,

    methods_generic_on: BTreeMap<String, Vec<&'a ast::Fn>>,

    global_env: TypeEnv,

    classes: ClassEnv,

    methods: MethodEnv,

    enum_variants: EnumVariants,

    specialized: BTreeSet<String>,

    enqueued: BTreeSet<String>,

    worklist: Vec<PendingSpecialization<'a>>,

    produced: Vec<ast::Item>,

}

impl<'a> Monomorphizer<'a> {

    fn infer(&self, e: &ast::Expr, env: &TypeEnv) -> PlumType {

        let ctx = CheckCtx { classes: &self.classes, methods: &self.methods, enum_variants: &self.enum_variants };

        crate::infer_expr(e, env, &ctx).unwrap_or(PlumType::TVar("_".to_string()))

    }

    fn rewrite_fn_body(&mut self, f: &mut ast::Fn) -> Result<(), String> {

        let mut env = self.global_env.clone();

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

            env.insert("self".to_string(), TypeScheme::mono(PlumType::TNamed(recv.clone())));

        }

        for p in &f.params {

            let ty = match &p.ty {

                ast::ParamType::Type(t) => crate::plum_type_from_ast(t),

                ast::ParamType::Variadic(t) => crate::plum_type_from_ast(t),

            };

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

        }

        match &mut f.body {

            ast::FnBody::Expr(e) => self.rewrite_expr(e, &env)?,

            ast::FnBody::Block(block) => self.rewrite_block(block, &mut env)?,

        }

        Ok(())

    }

    fn rewrite_block(&mut self, block: &mut ast::Block, env: &mut TypeEnv) -> Result<(), String> {

        for stmt in &mut block.stmts {

            self.rewrite_stmt(stmt, env)?;

        }

        Ok(())

    }

    fn rewrite_stmt(&mut self, stmt: &mut ast::Stmt, env: &mut TypeEnv) -> Result<(), String> {

        match stmt {

            ast::Stmt::Assign(a) => {

                for (target, value) in a.targets.iter().zip(a.values.iter_mut()) {

                    self.rewrite_expr(value, env)?;

                    let ty = self.infer(value, env);

                    env.insert(target.clone(), TypeScheme::mono(ty));

                }

            }

            ast::Stmt::Return(Some(e)) => self.rewrite_expr(e, env)?,

            ast::Stmt::Return(None) => {}

            ast::Stmt::If(if_) => {

                self.rewrite_expr(&mut if_.condition, env)?;

                self.rewrite_block(&mut if_.body, &mut env.clone())?;

                for ei in &mut if_.else_ifs {

                    self.rewrite_expr(&mut ei.condition, env)?;

                    self.rewrite_block(&mut ei.body, &mut env.clone())?;

                }

                if let Some(else_block) = &mut if_.else_ {

                    self.rewrite_block(else_block, &mut env.clone())?;

                }

            }

            ast::Stmt::While(w) => {

                self.rewrite_expr(&mut w.condition, env)?;

                self.rewrite_block(&mut w.body, &mut env.clone())?;

            }

            ast::Stmt::For(f) => {

                self.rewrite_expr(&mut f.iter, env)?;

                let mut inner = env.clone();

                for v in &f.vars {

                    inner.insert(v.clone(), TypeScheme::mono(PlumType::TInt));

                }

                self.rewrite_block(&mut f.body, &mut inner)?;

            }

            ast::Stmt::Expr(e) => self.rewrite_expr(e, env)?,

            ast::Stmt::Assert(e) => self.rewrite_expr(e, env)?,

            ast::Stmt::Match(m) => {

                for s in &mut m.subjects {

                    self.rewrite_expr(s, env)?;

                }

                let subject_ty = m.subjects.first().map(|s| self.infer(s, env)).unwrap_or(PlumType::TInt);

                for case in &mut m.cases {

                    let mut case_env = env.clone();

                    if let Some(ast::CasePattern::Name(n)) = case.patterns.first() {

                        let is_variant = n.chars().next().map(|c| c.is_uppercase()).unwrap_or(false)

                            && self.enum_variants.contains_key(n);

                        if !is_variant {

                            case_env.insert(n.clone(), TypeScheme::mono(subject_ty.clone()));

                        }

                    }

                    self.rewrite_block(&mut case.body, &mut case_env)?;

                }

            }

            ast::Stmt::Break | ast::Stmt::Continue | ast::Stmt::Todo => {}

        }

        Ok(())

    }

    fn resolve_class_instantiation(&mut self, call: &mut ast::ClassCall, env: &TypeEnv) -> Result<(), String> {

        let Some(class) = self.classes_generic.get(call.type_name.as_str()).copied() else { return Ok(()) };

        let params = class_generic_params(class);

        let mut bindings: BTreeMap<String, PlumType> = BTreeMap::new();

        for gp in &params {

            if let Some(field) = class.fields.iter().find(|f| f.ty.name == *gp) {

                if let Some(fa) = call.fields.iter().find(|fa| fa.name == field.name) {

                    bindings.insert(gp.clone(), self.infer(&fa.value, env));

                }

            }

        }

        if bindings.len() != params.len() {

            return Err(format!(

                "monomorphize: could not resolve all generic parameters for '{}' at this call site",

                call.type_name

            ));

        }

        let type_args: Vec<PlumType> = params.iter().map(|p| bindings[p].clone()).collect();

        let mangled = mangle(&call.type_name, &type_args);

        if !self.specialized.contains(&mangled) && !self.enqueued.contains(&mangled) {

            self.enqueued.insert(mangled.clone());

            self.worklist.push(PendingSpecialization::Class { base: class, subst: Substitution(bindings), mangled: mangled.clone() });

        }

        call.type_name = mangled;

        Ok(())

    }

    fn resolve_fn_instantiation(&mut self, call: &mut ast::FnCall, env: &TypeEnv) -> Result<(), String> {

        let Some(f) = self.fns_generic.get(call.name.as_str()).copied() else { return Ok(()) };

        let params = fn_generic_params(f);

        let mut bindings: BTreeMap<String, PlumType> = BTreeMap::new();

        for (param, arg) in f.params.iter().zip(call.args.iter()) {

            let gp = match &param.ty {

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

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

            };

            if params.contains(&gp) {

                let arg_expr = match arg {

                    ast::Arg::Positional(e) => e,

                    ast::Arg::Keyword { value, .. } => value,

                    ast::Arg::Pair { value, .. } => value,

                };

                bindings.entry(gp).or_insert_with(|| self.infer(arg_expr, env));

            }

        }

        if bindings.len() != params.len() {

            return Err(format!(

                "monomorphize: could not resolve all generic parameters for '{}' at this call site",

                call.name

            ));

        }

        let type_args: Vec<PlumType> = params.iter().map(|p| bindings[p].clone()).collect();

        let mangled = mangle(&call.name, &type_args);

        if !self.specialized.contains(&mangled) && !self.enqueued.contains(&mangled) {

            self.enqueued.insert(mangled.clone());

            self.worklist.push(PendingSpecialization::Fn { base: f, subst: Substitution(bindings), mangled: mangled.clone(), new_receiver: None });

        }

        call.name = mangled;

        Ok(())

    }

    fn rewrite_expr(&mut self, expr: &mut ast::Expr, env: &TypeEnv) -> Result<(), String> {

        match expr {

            ast::Expr::ClassCall(call) => {

                for fa in &mut call.fields {

                    self.rewrite_expr(&mut fa.value, env)?;

                }

                self.resolve_class_instantiation(call, env)?;

            }

            ast::Expr::FnCall(call) => {

                for arg in &mut call.args {

                    let e = match arg {

                        ast::Arg::Positional(e) => e,

                        ast::Arg::Keyword { value, .. } => value,

                        ast::Arg::Pair { value, .. } => value,

                    };

                    self.rewrite_expr(e, env)?;

                }

                self.resolve_fn_instantiation(call, env)?;

            }

            ast::Expr::Attribute(attr) => {

                self.rewrite_expr(&mut attr.object, env)?;

                if let ast::AttrKind::Method(call) = &mut attr.attr {

                    for arg in &mut call.args {

                        let e = match arg {

                            ast::Arg::Positional(e) => e,

                            ast::Arg::Keyword { value, .. } => value,

                            ast::Arg::Pair { value, .. } => value,

                        };

                        self.rewrite_expr(e, env)?;

                    }

                    // Method dispatch on a specialized receiver needs no rewrite here:

                    // once the receiver's construction site is rewritten to its mangled

                    // class name, the receiver's inferred static type IS that mangled

                    // name, and the specialized methods were registered under exactly

                    // that (mangled receiver, method name) key when their class was

                    // specialized (see the `PendingSpecialization::Class` arm below).

                }

            }

            ast::Expr::Binary(b) => { self.rewrite_expr(&mut b.left, env)?; self.rewrite_expr(&mut b.right, env)?; }

            ast::Expr::Bool(b) => { self.rewrite_expr(&mut b.left, env)?; self.rewrite_expr(&mut b.right, env)?; }

            ast::Expr::Compare(c) => { self.rewrite_expr(&mut c.left, env)?; self.rewrite_expr(&mut c.right, env)?; }

            ast::Expr::Not(inner) => self.rewrite_expr(inner, env)?,

            ast::Expr::Unary(u) => self.rewrite_expr(&mut u.operand, env)?,

            ast::Expr::Paren(inner) => self.rewrite_expr(inner, env)?,

            ast::Expr::Ternary(t) => {

                self.rewrite_expr(&mut t.condition, env)?;

                self.rewrite_expr(&mut t.then, env)?;

                self.rewrite_expr(&mut t.else_, env)?;

            }

            ast::Expr::Int(_) | ast::Expr::Float(_) | ast::Expr::String(_)

            | ast::Expr::Self_ | ast::Expr::Var(_) | ast::Expr::TypeName(_) => {}

        }

        Ok(())

    }

}

/// Runs the whole generics-monomorphization pass over `source`, producing a plain,

/// fully-concrete `ast::Source` with every generic `Class`/`Fn`/`Enum` template

/// replaced by zero or more mangled concrete specializations, and every remaining

/// item's body rewritten so its call sites reference those mangled names. The

/// result has no generic syntax left in it — `check_source`/`compile_source` run

/// on it completely unmodified.

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

    let (global_env, classes, methods, enum_variants) = crate::build_global_tables(source);

    let mut m = Monomorphizer {

        classes_generic: BTreeMap::new(),

        fns_generic: BTreeMap::new(),

        methods_generic_on: BTreeMap::new(),

        global_env,

        classes,

        methods,

        enum_variants,

        specialized: BTreeSet::new(),

        enqueued: BTreeSet::new(),

        worklist: Vec::new(),

        produced: Vec::new(),

    };

    for item in &source.items {

        match item {

            ast::Item::Class(c) if !c.generics.is_empty() => { m.classes_generic.insert(c.name.clone(), c); }

            _ => {}

        }

    }

    for item in &source.items {

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

            let receiver_is_generic = f.type_param.as_deref().map(|r| m.classes_generic.contains_key(r)).unwrap_or(false);

            if receiver_is_generic {

                m.methods_generic_on.entry(f.type_param.clone().unwrap()).or_default().push(f);

            } else if f.type_param.is_none() && !fn_generic_params(f).is_empty() {

                m.fns_generic.insert(f.name.clone(), f);

            }

            // A method whose receiver is NOT generic is left as a regular method below,

            // even if its own params/return happen to use a bare lowercase-letter type

            // name — that shape (a method introducing its own extra generic parameter)

            // is out of scope for this pass; see the plan's Global Constraints.

        }

    }

    for item in &source.items {

        match item {

            ast::Item::Class(c) if c.generics.is_empty() => m.produced.push(ast::Item::Class(c.clone())),

            ast::Item::Enum(e) if enum_generic_params(e).is_empty() => m.produced.push(ast::Item::Enum(e.clone())),

            ast::Item::Const(c) => m.produced.push(ast::Item::Const(c.clone())),

            ast::Item::Trait(t) => m.produced.push(ast::Item::Trait(t.clone())),

            ast::Item::Fn(f) => {

                let receiver_is_generic = f.type_param.as_deref().map(|r| m.classes_generic.contains_key(r)).unwrap_or(false);

                let is_generic_fn = f.type_param.is_none() && !fn_generic_params(f).is_empty();

                if !receiver_is_generic && !is_generic_fn {

                    let mut f2 = f.clone();

                    m.rewrite_fn_body(&mut f2)?;

                    m.produced.push(ast::Item::Fn(f2));

                }

            }

            _ => {} // generic Class/Enum declarations dropped here — templates only

        }

    }

    let mut guard = 0usize;

    while let Some(pending) = m.worklist.pop() {

        guard += 1;

        if guard > 10_000 {

            return Err("monomorphize: exceeded specialization limit (possible unbounded generic recursion)".to_string());

        }

        match pending {

            PendingSpecialization::Class { base, subst, mangled } => {

                if !m.specialized.insert(mangled.clone()) { continue; }

                m.produced.push(ast::Item::Class(specialize_class(base, &subst, &mangled)));

                if let Some(methods) = m.methods_generic_on.get(base.name.as_str()).cloned() {

                    for method in methods {

                        let mut specialized_method = specialize_fn(method, &subst, &method.name, Some(mangled.clone()));

                        m.rewrite_fn_body(&mut specialized_method)?;

                        m.produced.push(ast::Item::Fn(specialized_method));

                    }

                }

            }

            PendingSpecialization::Fn { base, subst, mangled, new_receiver } => {

                if !m.specialized.insert(mangled.clone()) { continue; }

                let mut specialized_fn = specialize_fn(base, &subst, &mangled, new_receiver);

                m.rewrite_fn_body(&mut specialized_fn)?;

                m.produced.push(ast::Item::Fn(specialized_fn));

            }

            PendingSpecialization::Enum { base, subst, mangled } => {

                if !m.specialized.insert(mangled.clone()) { continue; }

                m.produced.push(ast::Item::Enum(specialize_enum(base, &subst, &mangled)));

            }

        }

    }

    Ok(ast::Source { module: source.module.clone(), imports: source.imports.clone(), items: m.produced })

}

```

- [ ] **Step 4: Wire the pass into `check_source`**

In `plum-checker/src/lib.rs`, replace:

```rust

pub fn check_source(source: &ast::Source) -> CheckResult<()> {

    let mut errors: Vec<CheckError> = Vec::new();

    let (global_env, classes, methods, enum_variants) = build_global_tables(source);

    let ctx = CheckCtx { classes: &classes, methods: &methods, enum_variants: &enum_variants };

    for item in &source.items {

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

            let mut local_errors = check_fn(f, &global_env, &ctx);

            errors.append(&mut local_errors);

        }

    }

    if errors.is_empty() { Ok(()) } else { Err(errors) }

}

```

with:

```rust

pub fn check_source(source: &ast::Source) -> CheckResult<()> {

    let source = monomorphize::monomorphize_source(source).map_err(|e| vec![CheckError { message: e }])?;

    let mut errors: Vec<CheckError> = Vec::new();

    let (global_env, classes, methods, enum_variants) = build_global_tables(&source);

    let ctx = CheckCtx { classes: &classes, methods: &methods, enum_variants: &enum_variants };

    for item in &source.items {

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

            let mut local_errors = check_fn(f, &global_env, &ctx);

            errors.append(&mut local_errors);

        }

    }

    if errors.is_empty() { Ok(()) } else { Err(errors) }

}

```

- [ ] **Step 5: Wire the pass into `compile_source`**

In `plum-wasm-codegen/src/lib.rs`, find `pub fn compile_source(source: &ast::Source) -> Result<Vec<u8>, String> {` and add, as its very first line:

```rust

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

```

(The rest of the function already only ever reads `source.items`/`&source` by reference, so rebinding the parameter name to this new owned-then-reborrowed value requires no other changes in the function body.)

- [ ] **Step 6: Run the new checker tests**

Run: `cargo test -p plum-checker --test checker_tests generic_`

Expected: all four pass.

- [ ] **Step 7: Run the full workspace suite**

Run: `cargo test --workspace`

Expected: green — in particular, confirm no existing test that uses a generic-looking type name in a way this pass now treats differently regresses (e.g. `examples/types.plum`'s `Box(a)`/`Comparable(a: Ord)` declarations, which have zero instantiation sites anywhere in that file, should simply be dropped from the monomorphized output with no error, since `examples_test.rs` only requires the file to type-check, not that every declared item survives).

- [ ] **Step 8: Commit**

```bash

git add plum-checker/src/monomorphize.rs plum-checker/src/lib.rs plum-wasm-codegen/src/lib.rs plum-checker/tests/checker_tests.rs

git commit -m "feat(plum-checker): monomorphize generic classes/functions/methods/enums before checking and codegen"

```

---

### Task 3: Codegen tests, pathological-recursion guard test, examples, and docs

**Files:**

- Test: `plum-wasm-codegen/tests/codegen_tests.rs`

- Test: `plum-checker/tests/checker_tests.rs` (one more test)

- Modify: `examples/types.plum`, `examples/functions.plum` (or a new example file — see Step 3)

- Modify: `README.md`

**Interfaces:**

- Consumes: Task 2's `monomorphize_source`, wired transparently into `compile_source`.

- Produces: nothing further downstream — this is the final integration/documentation task.

- [ ] **Step 1: Write codegen tests proving the feature end-to-end**

Append to `plum-wasm-codegen/tests/codegen_tests.rs`:

```rust

#[test]

fn generic_class_specialized_at_two_types_does_not_alias() {

    let src = "\

type Box(a) =

  value: a

getIntValue<Box>() -> Int =

  self.value

useInt() -> Int =

  b = Box(value: 7)

  b.getIntValue()

main() -> Int =

  useInt()

";

    let source = parse(src);

    let bytes = compile_source(&source).expect("compile failed");

    assert_eq!(run_main(&bytes), 7);

}

#[test]

fn generic_function_called_at_multiple_concrete_types_runs_correctly() {

    let src = "\

identity(value: a) -> a =

  value

main() -> Int =

  identity(5) + identity(37)

";

    let source = parse(src);

    let bytes = compile_source(&source).expect("compile failed");

    assert_eq!(run_main(&bytes), 42);

}

#[test]

fn generic_method_on_generic_class_runs_correctly() {

    let src = "\

type Box(a) =

  value: a

getValue<Box>() -> Int =

  self.value

main() -> Int =

  b = Box(value: 9)

  b.getValue()

";

    let source = parse(src);

    let bytes = compile_source(&source).expect("compile failed");

    assert_eq!(run_main(&bytes), 9);

}

#[test]

fn transitively_generic_call_chain_runs_correctly() {

    let src = "\

identity(value: a) -> a =

  value

doubled(value: a) -> Int =

  identity(value) + identity(value)

main() -> Int =

  doubled(21)

";

    let source = parse(src);

    let bytes = compile_source(&source).expect("compile failed");

    assert_eq!(run_main(&bytes), 42);

}

#[test]

fn generic_enum_specialized_and_matched_runs_correctly() {

    let src = "\

enum Option =

  | Some(a)

  | None

unwrapOr(o: Option, default: Int) -> Int =

  match o

    Some(v) =>

      v

    None =>

      default

main() -> Int =

  unwrapOr(Some(13), 0)

";

    let source = parse(src);

    let bytes = compile_source(&source).expect("compile failed");

    assert_eq!(run_main(&bytes), 13);

}

```

- [ ] **Step 2: Write a checker test for the runaway-recursion guard**

Append to `plum-checker/tests/checker_tests.rs`:

```rust

#[test]

fn unbounded_recursive_generic_instantiation_is_a_clear_error() {

    // `Wrap(a)`'s own field is `Wrap(Box(a))` — every instantiation of `Wrap` at some

    // concrete `a` requires instantiating it again at `Box(a)`, a strictly larger type,

    // forever. This must fail with a clear, bounded error rather than hang or panic.

    let src = "\

type Box(a) =

  value: a

type Wrap(a) =

  inner: Wrap(Box(a))

use() -> Int =

  w = Wrap(inner: 5)

  1

";

    let source = parse(src);

    let result = check_source(&source);

    assert!(result.is_err());

    let errs = result.unwrap_err();

    assert!(errs[0].message.contains("monomorphize"), "got: {:?}", errs);

}

```

Run: `cargo test -p plum-checker --test checker_tests unbounded_recursive`

Expected: passes — the `guard > 10_000` cap in `monomorphize_source` (Task 2) returns a clear error well before any real resource exhaustion. If this test instead hangs or the guard doesn't trip because this particular shape doesn't actually reach the worklist the way you expect (e.g. because `Wrap`'s own field type is never a *call site* — it's just a declared, uninstantiated field type on a template that's never itself constructed with a concrete `a` anywhere reachable) — investigate and adjust the repro source until it genuinely exercises an unbounded worklist growth, since the guard's job is to bound runaway *specialization*, not merely to reject any nonsensical declaration.

- [ ] **Step 3: Extend the examples with real instantiations**

`examples/types.plum` and `examples/functions.plum` currently only *declare* generic items (no instantiation sites, so the monomorphization pass now correctly drops them with no error, but they're not actually exercised end-to-end). Append to `examples/functions.plum`:

```plum

useWrap() -> Bool =

  wrap(5)

usePair() -> Bool =

  pair(1, "x")

```

Append to `examples/types.plum`:

```plum

makeIntBox() -> Box =

  Box(value: 5)

makeStrBox() -> Box =

  Box(value: "x")

```

Run: `cargo test -p plum-checker --test examples_test` and `cargo test -p plum-wasm-codegen --test examples_test`

Expected: both pass — `types.plum` and `functions.plum` now exercise real generic instantiation, type-check, and compile.

- [ ] **Step 4: Update README's Known Gaps**

In `README.md`, remove this line from the Known Gaps list:

```markdown

- user-defined generics (they type-check but aren't monomorphized) — this also blocks `libs/std`'s actual `Option`/`Result`/`List`/`Map`, which are declared generically

```

and add, in its place:

```markdown

- `libs/std`'s actual `List`/`Map`/`Option`/`Result` still don't compile — they use several other unimplemented features (closures, `Nil`/optional chaining, decorators, colon-arrow return syntax) unrelated to generics, which are themselves now monomorphized and compiled correctly for the currently-documented generic syntax

```

Also update the "Generics" section's prose (currently ends with "There's no monomorphization/codegen for user-defined generics yet — they type-check permissively but don't compile to wasm.") to instead say generics are monomorphized and compiled, and reference the new examples.

- [ ] **Step 5: Run the full workspace and tree-sitter suites**

```bash

cargo test --workspace

cd tooling/tree-sitter-plum && npx --yes tree-sitter-cli test

```

Expected: fully green, zero known failures.

- [ ] **Step 6: Commit**

```bash

git add plum-wasm-codegen/tests/codegen_tests.rs plum-checker/tests/checker_tests.rs examples/types.plum examples/functions.plum README.md

git commit -m "test+docs: generics monomorphization complete; extend examples, update known gaps"

```