plum

# Plum WASM Codegen + Type Checker — Design Spec

**Date:** 2026-07-19  
**Status:** Approved

---

## Overview

Add a strict type checker and WASM code generator to the plum language compiler, following the same architecture as the sibling `hica` compiler (already present in `plum/hica/`).

Pipeline: `parse (plum-core) → check (plum-checker) → codegen (plum-wasm-codegen)`

---

## Crate Structure

Two new crates added to the workspace in `Cargo.toml`:

- `plum-checker` — type inference and checking
- `plum-wasm-codegen` — lowers checked AST to `.wasm` binary via `wasm_encoder`

Both depend on `plum-core` for the shared AST types.

---

## Type Checker (`plum-checker`)

### Core Types

```rust
pub type TypeEnv = BTreeMap<String, TypeScheme>;

pub struct TypeScheme {
    pub vars: Vec<String>,   // generic type params
    pub body: Box<PlumType>,
}

pub enum PlumType {
    TInt,
    TFloat,
    TBool,
    TStr,
    TUnit,
    TVar(String),            // fresh inference variable
    TFun(Vec<PlumType>, Box<PlumType>),
    TNamed(String),          // user-defined class/enum/trait name (v1: opaque)
}

pub struct InferState {
    pub counter: u64,        // fresh variable counter
}
```

### Error Reporting

```rust
pub struct CheckError {
    pub message: String,
}
pub type CheckResult<T> = Result<T, Vec<CheckError>>;
```

A non-empty error list halts compilation entirely (strict mode). Errors accumulate per-function so multiple errors are reported in one pass.

### Primitive Type Mapping

| Plum type | Internal  |
|-----------|-----------|
| `Int`     | `TInt`    |
| `Float`   | `TFloat`  |
| `Bool`    | `TBool`   |
| `Str`     | `TStr`    |
| `Unit`    | `TUnit`   |

### Checks in v1 (minimal core)

- **Variable scope**: `Assign` targets added to env; undeclared variable reference → error
- **Function signatures**: params added to local env; return expression type must match declared return type
- **Binary ops**: both operands must be same numeric type; result type = operand type
- **Boolean ops** (`&&`, `||`, `!`): operands must be `TBool`
- **Compare ops**: both operands same type; result = `TBool`
- **`if`/`else`**: all branches must return the same type (or `TUnit` for statement-style)
- **`for` range**: range operands must be `TInt`; body may be `TUnit`
- **`while`**: condition must be `TBool`
- **`FnCall`**: arity and argument types must match declared function signature
- **`return`**: type must match enclosing function's declared return type

### Out of scope for v1

Traits, classes, enums, and generic dispatch are **recognized** in the AST but produce an "unsupported in v1" error if their methods or constructors are invoked in checked code. Top-level `class`/`trait`/`enum` declarations are accepted without deep checking.

### Public API

```rust
pub fn check_source(source: &plum_core::ast::Source) -> CheckResult<()>;
```

---

## WASM Codegen (`plum-wasm-codegen`)

### WasmModule helper

Mirrors `hica-wasm-codegen`'s `WasmModule` struct — a thin builder over `wasm_encoder` sections (types, imports, functions, exports, memories, globals, data segments, tables, elements).

### CompileCtx

```rust
pub struct CompileCtx {
    pub module: WasmModule,
    pub func_ids: HashMap<String, u32>,
    pub func_sigs: HashMap<String, FuncSig>,
    pub current_locals: HashMap<String, u32>,
    pub label_count: u32,
    pub bump_offset: u32,       // linear memory bump allocator for strings
    control_stack: Vec<ControlFrame>,
}
```

### Type Mapping (Plum → WASM)

| Plum type | WASM ValType |
|-----------|-------------|
| `Int`     | `i64`       |
| `Float`   | `f64`       |
| `Bool`    | `i32`       |
| `Str`     | `i32` (ptr) |
| `Unit`    | (no value)  |

### Memory Layout

One linear memory (1 page = 64 KiB min). String literals are emitted into a data segment; a bump allocator pointer (global `i32`) tracks the next free byte for runtime string allocation.

### Codegen Scope (v1)

| Plum construct | WASM output |
|---|---|
| Top-level `fn` | `function` with matching type |
| `Int` / `Float` / `Bool` literals | `i64.const` / `f64.const` / `i32.const` |
| Arithmetic `BinOp` | `i64.add`, `i64.sub`, `f64.mul`, etc. |
| `BoolOp` | `i32.and`, `i32.or` |
| `CompareOp` | `i64.lt_s`, `f64.eq`, etc. |
| `if` / `else if` / `else` | `block` + `if` instructions |
| `for` (range `a..b`) | `loop` + `br_if` |
| `while` | `loop` + `br_if` |
| `Assign` (local) | `local.set` + `local.get` |
| `FnCall` | `call` |
| `return` | `return` |
| `Const` (top-level) | WASM `global` with constant initializer |
| `main()` | exported as `"main"` |

### Public API

```rust
pub fn compile_source(source: &plum_core::ast::Source) -> Result<Vec<u8>, String>;
```

Returns the raw `.wasm` bytes.

---

## CLI Integration (`plum-cli`)

New `compile` subcommand:

```
plum compile <file.plum> [-o output.wasm]
```

Steps:
1. Parse with `plum-core::parse_source`
2. Type-check with `plum-checker::check_source` — errors printed to stderr, exit 1
3. Codegen with `plum-wasm-codegen::compile_source`
4. Write `.wasm` to output path (default: input path with `.wasm` extension)

---

## Testing

### `plum-checker/tests/`

Unit tests per rule:
- Undeclared variable → error
- Wrong return type → error
- Binary op type mismatch → error
- Valid function → no errors

### `plum-wasm-codegen/tests/`

Integration tests:
- Compile `test/add.plum` → validate `.wasm` bytes with `wasmparser`
- Compile factorial function → run with `wasmtime` crate, assert result

---

## Reference

- hica type checker: `hica/crates/hica-checker/src/lib.rs`
- hica WASM codegen: `hica/crates/hica-wasm-codegen/src/lib.rs`
- plum AST: `plum-core/src/ast.rs`