plum

# General enum support (checker + codegen)

## Problem

Today only `Bool`'s built-in `True`/`False` variants have a runtime representation
(`i32` 1/0). Any user-declared `enum` — payload-free (`Color = Red | Green | Blue`)
or payload-carrying (`Option = Some(a) | None`) — type-checks permissively but
fails to compile: `plum-wasm-codegen` hits the hardcoded
`"codegen: enum variant pattern '{}' is not yet supported (only True/False)"` error
(`plum-wasm-codegen/src/lib.rs:915`) for any non-Bool tag or constructor pattern in
`match`, and there's no construction path for payload variants like `Some(v)` at all.

This is scoped as a standalone, tractable slice of the larger "implement the
standard library" ambition. **It does not attempt generics monomorphization.**
`libs/std/option.plum` and `result.plum` use generic type params (`a`, `b`) and
will remain blocked on the separate, larger generics-monomorphization gap. This
work targets *concrete* user-declared enums only (e.g. a non-generic `Option`-shaped
enum over a specific type, or `Color`, or `Pair(Int, Str)`).

## Runtime representation

Every enum value is a single `i32`, matching the existing `Bool` scheme:

- **Payload-free variant** (`Red`, `None`, `True`, `False`): the `i32` is the
  variant's tag number directly — a small int.
- **Payload variant** (`Some(a)`, `Ok(a)`, `Pair(a, b)`): the `i32` is a pointer
  into the bump heap (which starts at address 65536, the second 64KiB page) to a
  struct `[tag: i32][field0][field1]...`, using the exact bump-alloc/store/load
  mechanism already used for class instance fields.

Tags are assigned per-enum, 0-based in declaration order across *all* variants
(payload and non-payload share one numbering) — e.g. `Option`: `Some`=0, `None`=1.

Because heap pointers are always ≥ 65536 and per-enum tags are small ints, a
payload-free tag value can never collide with a payload variant's pointer value,
so no separate discriminant bit is needed — matching on a bare tag pattern is a
direct `i32` comparison regardless of whether the enum has other payload variants.

## Checker changes (`plum-checker`)

`EnumVariants` (currently `BTreeMap<variant_name, enum_name>`) is extended to also
carry, per variant: its 0-based tag index and its field type names (parallel to
`EnumVariant.fields: Vec<String>` in the AST). This is purely additive — existing
lookups (`contains_key`, enum-name-of) are unaffected, and no currently-accepted or
currently-rejected program changes behavior. Type-checking of enum construction and
matching already works today per the README; this just carries enough data through
for codegen to compute struct layouts and payload types without re-deriving them
from the AST.

## Codegen — construction

A capitalized call expression (`Some(v)`, `Pair(a, b)`) currently only has meaning
for class instantiation. It gets a parallel variant-construction path, chosen by
looking up the callee name in the (extended) enum variants table:

- **No-payload variant used as a bare value** (`None`, `Red`, and `True`/`False`
  unchanged): compiles to `i32.const <tag>`.
- **Payload variant call**: bump-allocate `4 * (1 + field_count)` bytes, store the
  tag at offset 0, store each argument at its field offset using the same
  width-dependent store logic (i32/i64/f64) already used for class fields, leave
  the base pointer on the stack as the resulting value.

## Codegen — match lowering

Replace the current hardcoded-to-Bool error path
(`plum-wasm-codegen/src/lib.rs:901-918`, `compile_variant_eq_arm`) with a general
variant-tag test:

- **Bare tag pattern** (`Red`, `None`, `True`, `False`): `subject == i32.const <tag>`.
- **Constructor pattern** (`Some(v)`, `Pair(a, b)`): test that `subject`'s stored
  tag word (load `i32` at offset 0 of the pointer) equals the variant's tag, then
  for each pattern-bound name, load the corresponding field offset from the
  pointer and bind it as a local before evaluating the arm body.

Multi-subject `match` and non-constructor/non-tag patterns (already-known gaps)
remain out of scope.

## Testing plan

- **Checker tests** (`plum-checker/tests/checker_tests.rs`): payload-free enum
  (`Color`), payload enum (concrete, non-generic `Option`-shaped enum), and
  constructor-pattern matches — confirm the extended `EnumVariants` table changes
  no pass/fail outcome versus today.
- **Codegen tests** (`plum-wasm-codegen/tests/codegen_tests.rs`, compiled and run
  via wasmtime matching existing style): construct + match a payload-free variant;
  construct + destructure a payload variant in `match`; a multi-field variant
  (`Pair(a, b)`); a variant used as a class field/method to confirm interop with
  existing class codegen.
- **Examples**: extend `examples/match.plum` (or add a new example) with a
  concrete user-declared enum exercised end-to-end; update the README's Known
  Gaps section to drop the now-solved bullet (non-Bool enum-tag and constructor
  patterns), while keeping the user-defined-generics bullet as-is.

## Out of scope

- Generics monomorphization (separate, larger effort — blocks `libs/std`'s actual
  `Option`/`Result`/`List`/`Map`).
- Multi-subject `match`.
- Any pattern kind beyond bare tag / constructor (literal, binding, wildcard
  already work and are untouched).