5ef4579 | plum

git clone https://git.pyrossh.dev/plum

A statically typed, imperative programming language inspired by rust, python

5ef4579 — Peter John 2026-08-10T11:10:35+05:30

feat(plum-wasm-codegen): add wasm-gc type-section emitter (unconsumed) and GC-enabled test Engine

Files changed (4) hide show

docs/superpowers/plans/2026-07-25-wasm-gc-migration.md +229 -0
plum-wasm-codegen/src/lib.rs +221 -6
plum-wasm-codegen/tests/codegen_tests.rs +486 -6
plum-wasm-codegen/tests/examples_test.rs +12 -3

docs/superpowers/plans/2026-07-25-wasm-gc-migration.md ADDED Viewed

@@ -0,0 +1,229 @@
+# Wasm-GC Migration Implementation Plan
+> **For agentic workers:** Steps use checkbox (`- [ ]`) syntax for tracking. Work task-by-task, in order — later tasks assume earlier ones landed.
+**Goal:** Replace `plum-wasm-codegen`'s hand-rolled bump-allocator memory model with wasm-gc (`struct`/`array` types, `ref`/`ref null`, `struct.new`, `ref.test`/`br_on_cast`), per `docs/superpowers/specs/2026-07-25-wasm-gc-migration-design.md`. Retire the bump allocator, `MemoryType`, and `bump_global` entirely. Unblocks `libs/std/list.plum`'s `todo` methods (`add`/`set`/`removeAt`/`remove`/`clear`/`reverse`), which is the concrete deliverable.
+**Architecture:** One wasm-gc `struct` type per concrete (post-monomorphization) class/struct. Per enum, one abstract supertype `struct` plus one concrete subtype `struct` per variant (wasm-gc declared subtyping), matched via `ref.test`/`br_on_cast` — **including `Bool`**, per explicit user decision below. `Str` becomes `array<i8>`. The linear memory, `MemoryType`, and `bump_global` are deleted entirely once nothing depends on them — static string data moves to a **passive** data segment consumed via `array.new_data` (no active memory needed for it at all).
+**Decisions made during planning that the design spec left open** (read these before starting — they resolve real ambiguities, not stylistic preferences):
+1. **Bool is a full wasm-gc struct, no special-casing** (explicit user decision — the alternative, keeping `Bool` as a raw `i32` for cheap control flow, was rejected in favor of literal spec uniformity). Consequence: every `if`/`while` condition, `&&`/`||` operand, and `assert` — anywhere a `Bool` value drives wasm's native control flow (which requires a raw `i32`, not a `ref`) — needs a `ref.test (ref $True)` inserted to convert the `Bool` ref into an `i32` immediately before it's consumed by `Instruction::If`/`BrIf`. Comparison operators (`==`, `!=`, `<`, etc.) go the other direction: the native predicate produces an `i32` 0/1, which then selects between the pre-allocated `$True`/`$False` singletons (see next point) via a small `if/else` yielding a `ref`.
+2. **Payload-free variants are pre-allocated once as globals, not constructed per-use.** `True`, `False`, `None`, and any other zero-field variant of any enum are immutable and interchangeable, so each gets exactly one `struct.new` at a module-initialization point, stored in a `global`; every subsequent bare reference (`True`, `None`, a comparison result, a discriminant-free `enum` variant) is a `global.get` of that singleton, not a fresh allocation. This avoids needless GC churn for the single highest-frequency value shape in the language (every boolean expression).
+3. **Closure env pointers are `anyref` in the shared `call_indirect` signature**, not a per-closure concrete type. Every closure literal has a structurally different captured-variable shape, but all closures of the same plum `fn(...)` type must share one wasm function-type for `call_indirect` to dispatch across them uniformly — exactly the role `i32` (an untyped address) plays today. Each closure's own compiled body does `ref.cast (ref $ItsOwnEnvType)` on the incoming `anyref` as its first instruction, recovering its concrete, statically-typed env struct before reading captured fields. The closure value itself (`{table_index, env_pointer}`) becomes a two-field `struct` (`i32`, `anyref`) instead of a bump-allocated pair.
+4. **String data uses a passive data segment + `array.new_data`**, not an active one — this needs no `memory` section at all, which is what lets the memory section disappear completely rather than sticking around just for string constants.
+**Tech Stack:** `wasm-encoder` 0.220 (already supports `CoreTypeEncoder::struct_`/`array`/`subtype`/`rec`, `Instruction::StructNew`/`StructGet`/`StructSet`/`ArrayNewData`/`RefTestNonNull`/`BrOnCast`, `RefType`/`HeapType::Concrete` — verified directly against the vendored source, no upgrade needed), `wasmtime` 28 (`Config::wasm_gc`/`wasm_function_references` exist and are reachable — the `"gc"`/`"gc-drc"`/`"gc-null"` cargo features are already in wasmtime's `default` feature set, so no `Cargo.toml` change is needed, just calling the `Config` methods in test setup). **Caveat directly from wasmtime's own doc comment on `Config::wasm_gc`: "Wasmtime's implementation of the GC proposal is still in progress and generally not ready for primetime."** Budget time in Task 1 to discover real limitations empirically, not just from docs.
+## Global Constraints
+- Spec: `docs/superpowers/specs/2026-07-25-wasm-gc-migration-design.md`. This plan's four numbered decisions above fill gaps that spec left unresolved (Bool, closures, singleton variants, string data segment kind) — treat them as binding, not as this plan's own invention to second-guess mid-implementation.
+- This is fundamentally **not** an incrementally-toggleable migration: the moment `Str` (or anything) becomes a `ref`, every class/struct/enum that can hold one transitively can no longer live in linear memory (wasm-gc references cannot be stored in linear memory at all — that's the point of the proposal's separate reference universe). Task 2 is therefore one large, multi-step "big bang" task that switches construction, field/variant access, match dispatch, strings, and closures over together — expect it to be the bulk of this plan's work, and expect the codebase to be non-compiling partway through its steps until the whole task lands. Do not attempt to keep every individual step's diff independently green; the task-level `cargo test --workspace` at the end of Task 2 is the real gate.
+- `plum-checker`'s type-checking/monomorphization needs **no changes** — it already resolves every generic instantiation to a concrete type before codegen runs (confirmed by reading `plum-checker/src/monomorphize.rs`'s existing role in `compileSource`). If you find this assumption wrong, stop and report BLOCKED rather than silently expanding scope into `plum-checker`.
+- Run `cargo build --workspace --all-targets` after every step that touches `plum-wasm-codegen/src/lib.rs` (compilation alone is a fast, cheap checkpoint even mid-task before behavior is testable), and `cargo test --workspace` at the end of every task.
+- `[T]` array literals/indexing and wasm exception-handling remain explicitly out of scope (per the spec) — do not add them opportunistically because GC types make them easier.
+---
+### Task 1: Wasmtime GC config verification + wasm-gc type-section emitter foundation
+**Files:**
+- Modify: `plum-wasm-codegen/Cargo.toml` (only if the empirical check in Step 1 finds the default features insufficient)
+- Modify: `plum-wasm-codegen/tests/codegen_tests.rs`, `plum-wasm-codegen/tests/examples_test.rs`
+- Modify: `plum-wasm-codegen/src/lib.rs`
+**Interfaces:**
+- Consumes: nothing (bottom of this plan's dependency chain).
+- Produces: every `wasmtime::Engine`/`Config` used in tests has the GC proposal enabled; a new type-section emitter that, given the checker's monomorphized `Source`, emits one wasm-gc `struct` per concrete class, one abstract-supertype-plus-per-variant-subtype set per enum (Bool included, built in exactly like the existing hardcoded `True`/`False` `EnumVariantInfo` registration), and one `array<i8>` type for `Str` — **wired up but not yet consumed by any real codegen path**, so all EXISTING tests (still running through the untouched bump-allocator codegen) stay green. This task is purely additive.
+- [ ] **Step 1: Confirm wasmtime's GC `Config` actually works empirically, first**
+Before writing any type-emitter code, write a throwaway test (in `codegen_tests.rs`, can be deleted/replaced by Task 2) that: builds a `wasmtime::Config`, calls `.wasm_gc(true)` (and `.wasm_function_references(true)` — check by reading `wasmtime-28.0.1`'s `config.rs`, vendored at `~/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/wasmtime-28.0.1/src/config.rs`, whether GC has an undeclared dependency on function-references that isn't auto-enabled), constructs an `Engine` from it, and hand-encodes (via `wasm_encoder` directly, no plum involved) the smallest possible module with one GC struct type, one function that does `struct.new_default` + returns it typed as `(ref null $T)`, and confirms it validates AND instantiates+runs under that `Engine`. If this fails or exhibits a real engine limitation, that finding drives every subsequent step — report it before proceeding, don't route around it silently.
+- [ ] **Step 2: Update the test harness's `Engine`/`Config` construction**
+Read the current `Engine::default()` (or equivalent) call sites in `codegen_tests.rs` and `examples_test.rs` (search `wasmtime::Engine`) and replace with the `Config` confirmed working in Step 1. Every test in both files must still pass unchanged (they're still exercising the untouched bump-allocator codegen at this point) — this step is purely "can a GC-enabled engine still run today's non-GC output," which it should, since enabling a feature doesn't retroactively require using it.
+- [ ] **Step 3: Read the current type-registration surface before extending it**
+Read `plum-checker`'s `ClassEnv`/`EnumVariants`/`EnumVariantInfo` definitions (`plum-checker/src/lib.rs`) and `plum-wasm-codegen`'s `CompileCtx`/`LocalCtx` (`plum-wasm-codegen/src/lib.rs`) exact current fields — this plan's earlier research read them as of the enum-discriminant-values plan's completion, but re-verify, since intervening work may have touched them.
+- [ ] **Step 4: Add a GC type registry, populated but unconsumed**
+Add a new struct (e.g. `GcTypeRegistry`) that, given the monomorphized `ast::Source` plus the existing `ClassEnv`/`EnumVariants` tables, assigns and records a wasm type-section index for: every concrete class name, every enum's abstract supertype, every enum variant's concrete subtype, and one shared `array<i8>` index for `Str`. Emit these into a real `TypeSection` via `CoreTypeEncoder::struct_`/`array`/`subtype` (structs need `SubType { is_final: false, supertype_idx: None, ... }` for a class since it needs no subtyping, but an enum's supertype needs `is_final: false` so variants CAN subtype it, and each variant subtype needs `SubType { supertype_idx: Some(super_idx), ... }`) — group the whole enum's supertype+variants in one `rec` group (`CoreTypeEncoder::rec`) since wasm-gc subtyping requires supertype and subtype to be declared in the same recursive group or supertype declared earlier in an earlier group; read `wasm-encoder`'s `rec`/`subtype` doc comments (`~/.cargo/registry/.../wasm-encoder-0.220.1/src/core/types.rs`) to get the ordering constraint exactly right. Thread the resulting index tables through `CompileCtx` as new fields (e.g. `class_type_idx: HashMap<String, u32>`, `enum_super_type_idx: HashMap<String, u32>`, `variant_type_idx: HashMap<String, u32>`, `str_type_idx: u32`), populated in `compileSource` but not read by anything else yet.
+- [ ] **Step 5: Add a corresponding Rust test proving the type section is well-formed**
+Add a test that compiles a small source (one class, one enum with a payload variant and a payload-free variant) through `compileSource`, and asserts the resulting bytes validate via `wasmparser::validate` under the GC-enabled config from Step 1 — this proves the new type section alone (still unused by real codegen) is well-formed, before Task 2 starts depending on it.
+- [ ] **Step 6: Run full verification**
+`cargo build --workspace --all-targets` then `cargo test --workspace`. Expected: 100% pass, identical results to before this task — nothing behavioral changed yet.
+- [ ] **Step 7: Commit**
+```bash
+git add plum-wasm-codegen/src/lib.rs plum-wasm-codegen/tests/codegen_tests.rs plum-wasm-codegen/tests/examples_test.rs plum-wasm-codegen/Cargo.toml
+git commit -m "feat(plum-wasm-codegen): add wasm-gc type-section emitter (unconsumed) and GC-enabled test Engine"
+```
+---
+### Task 2: The big switchover — construction, field/variant access, match dispatch, strings, and closures onto wasm-gc
+**Files:** `plum-wasm-codegen/src/lib.rs` (the overwhelming majority of this task), `plum-wasm-codegen/tests/codegen_tests.rs`, `plum-wasm-codegen/tests/examples_test.rs`
+**Interfaces:**
+- Consumes: the type registry from Task 1.
+- Produces: every codegen path that currently reads/writes `ctx.bump_global` instead does `struct.new`/`struct.get`/`struct.set`/`array.*`; `match` dispatch uses `ref.test`/`br_on_cast`; the memory section, `bump_global`, `HEAP_BASE`, `STRING_BASE` are deleted with nothing left depending on them.
+This task is large enough that its steps are grouped by concern. Within each concern, **read the current exact code first** — this plan describes shapes and gives file:line references from the research pass that wrote it, but by the time you reach a given step, earlier steps in this same task will have already changed surrounding code. Re-verify against the live file, not this plan's prose.
+#### 2a. Bool/enum singletons and control-flow conversion (do this first — nearly everything else depends on being able to produce/consume a Bool)
+- [ ] **Step 1: Read `compileSource`'s current initialization sequence, `compileStmt`'s `If`/`While` arms, `boolean_operator`/comparison codegen, and `assert` codegen**
+These are all in `plum-wasm-codegen/src/lib.rs` — find them by searching `ast::Stmt::If`, `ast::Stmt::While`, `ast::Expr::Bool(`, `ast::Expr::Compare(`, `ast::Stmt::Assert`.
+- [ ] **Step 2: Emit one global per payload-free variant across the whole program (including `True`/`False`)**
+In `compileSource`, after the type registry (Task 1) is built, walk every enum's variants (plus the built-in `Bool`) and for each payload-free one, emit a `global` (mutable: false is ideal but wasm-gc struct globals may need an initializer expression capable of `struct.new` — read `wasm_encoder`'s `ConstExpr`/`GlobalSection` to confirm whether a GC `struct.new` is legal inside a global's constant-initializer expression under this wasm-gc revision; if not, fall back to a `start` function that runs once and stores each singleton into a mutable global before `main`/any export can run). Record `variant_name -> global_index` in a new `CompileCtx` field.
+- [ ] **Step 3: Rewrite conditional control flow to convert Bool refs to i32 via `ref.test`**
+Wherever a `Bool`-typed value currently feeds `Instruction::If`/`BrIf` unchanged (it's already an i32 today), insert `Instruction::RefTestNonNull(HeapType::Concrete(true_variant_type_idx))` immediately before it. This applies to at least: `if`/`else if` conditions, `while` conditions, `assert`, and short-circuit `&&`/`||` (which currently, per existing codegen, likely already lower to nested `If` blocks for short-circuiting — read the current `boolean_operator` codegen to confirm the exact shape before changing it).
+- [ ] **Step 4: Rewrite comparison operators to produce a Bool ref from a native i32 predicate**
+Currently a comparison (`==`, `<`, etc.) directly leaves an i32 on the stack as the Bool result. Change it to: compute the native i32 predicate as today, then `Instruction::If(BlockType::Result(bool_ref_type))` / push `GlobalGet(true_singleton)` / `Else` / `GlobalGet(false_singleton)` / `End`, so the result is a proper `Bool` ref matching every other Bool-producing expression.
+- [ ] **Step 5: Update every OTHER payload-free bare-variant construction site to use its singleton global instead of allocating**
+Search for the current handling of `ast::Expr::TypeName(n)` where `info.field_types.is_empty()` (bare tag construction) — this currently does `Instruction::I32Const(info.tag)`; change it to `Instruction::GlobalGet(singleton_idx)`.
+- [ ] **Step 6: Build and run affected tests only, iterating**
+`cargo build -p plum-wasm-codegen` first (fast compile-only check — expect many errors from downstream code still assuming i32 Bool/tags, which is fine, that's 2b/2c/2d's job). Do not attempt `cargo test` yet — the crate won't fully compile again until struct/enum construction (2b) and match dispatch (2d) also land, since they're mutually dependent on the same representation.
+#### 2b. Struct/class construction and field access
+- [ ] **Step 1: Read the current `ast::Expr::ClassCall` construction arm and the `Attribute`/`Field` read/write codegen**
+Search `ast::Expr::ClassCall`, `ast::AttrKind::Field`, `ast::AssignTarget::Field`.
+- [ ] **Step 2: Rewrite construction to `struct.new`**
+For each `ClassCall`, look up the class's declared field order (not `call.fields`'s written order — construction must push values in DECLARATION order for `struct.new`). For each declared field, find the matching `call.fields` entry by name and `compileExpr` its value onto the stack; once every field's value is pushed, emit `Instruction::StructNew(class_type_idx)`. The `classcall_scratch` local is very likely no longer needed for this case (no bump-pointer bookkeeping requires holding an intermediate address — verify by reading whether anything else in the current code relies on that scratch slot for `ClassCall` specifically before deleting its allocation for this case).
+- [ ] **Step 3: Rewrite field reads to `struct.get`**
+Replace the current class-field-read arm's `emitLoad` at a byte offset with `compileExpr` (pushes the object ref) followed by `Instruction::StructGet { struct_type_index: class_type_idx, field_index }`.
+- [ ] **Step 4: Rewrite field writes (`self.x = ...`, chained `a.b.c = ...`) to `struct.set`**
+Same shape: compile the object ref, compile the new value, `Instruction::StructSet { struct_type_index, field_index }`. `StructSet`'s stack order — verify from `wasm-encoder`'s encode impl or the wasm-gc spec whether it expects `(struct_ref, value)` or `(value, struct_ref)` push order; get this from the actual instruction encoding, not assumption, since getting it backwards produces a type-valid-looking-in-isolation-but-wrong-at-runtime bug that validation may not always catch depending on other stack contents.
+- [ ] **Step 5: Rewrite discriminant-enum field access (`self.n` on an `enum Foo(n: Int)`)** analogously, through `ctx.enum_params`, using `StructGet`/`StructSet` against the enum's own struct layout with the `field_idx + 1` tag-slot offset convention preserved conceptually (though the "+1 for tag" byte-offset trick is a linear-memory artifact — under wasm-gc each variant subtype simply has its own explicit field list starting at field index 0 for the first real field, no tag slot needed at all, since the tag IS the type itself now, discoverable via `ref.test`, not a stored value read at a fixed offset).
+#### 2c. String migration to `array<i8>`
+- [ ] **Step 1: Read the current string literal encoding, `registerStringConcatHelper`, `registerIntToStringHelper`, and string interpolation codegen**
+Search `compile_static_string` (or equivalent), `registerStringConcatHelper`, `registerIntToStringHelper`.
+- [ ] **Step 2: Static string literals become passive-data-segment `array.new_data`**
+Each string literal's bytes go into one passive `DataSection::passive(bytes)` segment (no active memory offset — confirm `wasm_encoder`'s `DataSection::passive` doesn't require a preceding memory section to exist at all, per this plan's Decision 4). At the literal's use site, emit `Instruction::ArrayNewData { array_type_index: str_type_idx, array_data_index }`.
+- [ ] **Step 3: Rewrite `registerStringConcatHelper` against `array.new`/`array.copy`**
+Read the exact current helper body first. The new version needs the combined length (`array.len` on both inputs, or track lengths already known from a length-prefix design if you keep one — decide whether `Str`'s `array<i8>` needs an explicit stored length or relies on `array.len`, and note that GC arrays DO track their own length natively, so a manual length prefix is no longer needed at all, simplifying this over the current length-prefixed-blob design), allocates a new array of that combined size (`array.new_default` sized dynamically — check whether `array.new_default` accepts a non-constant size operand; it does, per the wasm-gc spec, size is a runtime i32 operand), then two `Instruction::ArrayCopy { array_type_index_dst, array_type_index_src }` calls to copy each source's bytes into the destination at the right offset.
+- [ ] **Step 4: Rewrite `registerIntToStringHelper` similarly** — read its current byte-writing loop and adapt each byte store to `array.set` (or build into a fixed-size scratch and `array.new_data`-style copy, whichever the current algorithm's shape most directly maps to).
+- [ ] **Step 5: Update string interpolation codegen** to call the rewritten helpers; verify `Str`-typed class/enum fields (now `ref null $StrArray` instead of i32) round-trip correctly through 2b/2d's `struct.get`/`struct.set` and `ref.test`/variant-subtype field lists.
+#### 2d. Match dispatch via `ref.test`/`br_on_cast`
+- [ ] **Step 1: Read `compileMatch`, `compileMatchArmsMulti`, `compileCasePositions`, `compileVariantEqArm` (or its current name — it may have been renamed during the camelCase pass), `compileVariantConstructorArm`, and `compileFieldPatterns` in full before changing any of them** — this is the most intricate part of the existing codegen (recursive multi-subject, multi-position, nested-constructor-pattern dispatch) and the part most likely to have subtle behavioral requirements not obvious from a partial read.
+- [ ] **Step 2: Replace the `HEAP_BASE` range-check + tag-load-and-compare pattern with `ref.test`**
+Every place that currently does "range-check against `HEAP_BASE`, then conditionally load+compare a tag" (both the top-level bare-Name/Class-pattern arms and the nested `compileFieldPatterns` equivalents) becomes a single `Instruction::RefTestNonNull(HeapType::Concrete(variant_type_idx))` (or `RefTestNullable` if the value can legitimately be null in context — decide per call site) directly on the subject ref, producing the same "did this match" i32 the existing `If`/`Else` structure around it already expects — the surrounding control-flow shape (fall through to `compileMatchArmsMulti(rest, ...)` on mismatch) doesn't need to change, only how the boolean test itself is computed.
+- [ ] **Step 3: Replace payload-field extraction with `ref.cast` + `struct.get`**
+Where a matched constructor pattern currently loads a field via `emitLoad(field_vt, offset)` from the raw pointer, first `Instruction::RefCastNonNull(HeapType::Concrete(variant_type_idx))` (narrowing the statically-typed-as-supertype subject to its concrete variant subtype — the match arm's binding scope is exactly where this narrowing is valid) then `Instruction::StructGet { struct_type_index: variant_type_idx, field_index }`.
+- [ ] **Step 4: Consider (but don't require) using `br_on_cast` for the top-level dispatch chain** — the spec's Components section suggests `ref.test`/`br_on_cast` as the replacement mechanism; a straightforward `ref.test` + `if/else` chain (mirroring today's control-flow shape exactly, per Step 2) is very likely simpler to get right than restructuring into `br_on_cast`'s branch-table-like shape, and is equally correct. Only reach for `br_on_cast` if the `if/else` chain form turns out to hit a real wasm-gc validation or structural limitation — don't restructure working control flow for its own sake.
+#### 2e. Closures
+- [ ] **Step 1: Read `compileClosureLiteral`, `compileClosureCall`, `compileClosureBody`, and the `Collector`'s closure-discovery pass in full.**
+- [ ] **Step 2: Give every closure literal its own env `struct` type**, one field per captured variable in `free_vars` order, field types matching each captured variable's own type (which may itself now be a `ref` type post-2b/2c). Register these in the type registry alongside classes/enums.
+- [ ] **Step 3: Rewrite `compileClosureLiteral`**: build the env via `struct.new` (pushing each captured local's current value, per Decision 3 — snapshot-by-value semantics are unchanged, only the allocation mechanism changes), then build the 2-field closure struct `{i32 table_index, anyref env}` via `struct.new`, casting/widening the concrete env ref to `anyref` for storage (a supertype widening — confirm whether `wasm-encoder`/wasm-gc requires an explicit instruction for this or whether it's implicit at the type-checking level when a subtype value is used where a supertype/`anyref` is expected; if implicit, no extra instruction is needed).
+- [ ] **Step 4: Rewrite `compileClosureBody`**: its first instructions must `RefCastNonNull` (or the nullable variant, matching the declared param type) the incoming `anyref` env parameter down to `(ref $ThisClosuresEnvType)` before any captured-field reads, then use `struct.get` for each.
+- [ ] **Step 5: Update the shared `call_indirect` function-type signatures** (`fnParamTypeToWasmSig`/`ClosureSigKey` and wherever `call_indirect` types are registered/deduped) so the env-pointer parameter position is `ValType::Ref(RefType::ANYREF)` instead of `ValType::I32`, everywhere this shape is constructed.
+#### 2f. Retire the bump allocator entirely
+- [ ] **Step 1: Remove `HEAP_BASE`, `STRING_BASE`, `bump_global` (the field, its threading through `CompileCtx`/`LocalCtx`, and its initialization in `compileSource`), and the `addMemory`/memory-section code in `WasmModule::finish`** once `cargo build -p plum-wasm-codegen` shows nothing references them anymore. If anything still does, that's a sign an earlier 2a–2e step was missed or incomplete — go back, don't leave a partial bump-allocator fallback path.
+- [ ] **Step 2: Remove now-dead scratch-slot bookkeeping** (`classcall_scratch` etc., in `Collector` and `LocalCtx`) for any use case fully replaced by direct stack-order `struct.new` construction (per 2b Step 2) — but only what's actually provably dead; `match`'s subject-holding scratch locals are still needed (now typed as `ref null` instead of `i32`), don't remove those.
+#### 2g. Full verification for Task 2
+- [ ] **Step 1: `cargo build --workspace --all-targets`** — iterate until clean.
+- [ ] **Step 2: Update every existing `codegen_tests.rs`/`examples_test.rs` test that encoded assumptions about the old representation** (e.g. anything asserting raw byte layout, or relying on `HEAP_BASE`-adjacent behavior) — re-verify each still asserts the right OBSERVABLE behavior (a program's computed result), not the old mechanism.
+- [ ] **Step 3: `cargo test --workspace`** — expected: 100% pass. This is the real gate for this entire task; do not commit Task 2 before this is green.
+- [ ] **Step 4: Commit**
+```bash
+git add plum-wasm-codegen/src plum-wasm-codegen/tests
+git commit -m "feat(plum-wasm-codegen): migrate structs, enums, strings, and closures to wasm-gc"
+```
+---
+### Task 3: Implement `List`'s `todo` methods against the new struct representation
+**Files:** `libs/std/list.plum`, `plum-wasm-codegen/tests/codegen_tests.rs`
+**Interfaces:**
+- Consumes: `struct.new`/`struct.set`/`ref null` field semantics from Task 2 — specifically, that unlinking a `Node` (overwriting a `next`/`prev` field with `None`) makes it unreachable and GC-reclaimed with no explicit free.
+- Produces: `add`, `set`, `removeAt`, `remove`, `clear`, `reverse` on `List[T]` (currently `todo`) have real implementations; `Map` (built on `List`) works transitively.
+- [ ] **Step 1: Read `libs/std/list.plum`'s current `Node`/`List` field declarations and the already-implemented `get`/`length`/`each`/`map` methods** for the established style (`Option[Node]` traversal via `match current`) to match.
+- [ ] **Step 2: Implement `add`** — append (or prepend, per the existing doc comment on `add` — re-read it; the comment currently says "adds the specified elements to the start of the list" — confirm this is the intended semantic, since "add" more commonly means append, and fix the comment or the implementation, whichever is actually wrong, rather than silently implementing whichever is more convenient) by splicing a new `Node` in via `self.tail`/`self.head` and updating `size`.
+- [ ] **Step 3: Implement `set`** — traverse to index `i` (mirroring `get`'s traversal), overwrite the found node's `value` field, return `Some(oldValue)` or `None` if out of bounds.
+- [ ] **Step 4: Implement `removeAt`/`remove`** — traverse to the target node, splice it out by rewriting its neighbors' `prev`/`next` to point at each other (or to `None` at the list's ends, updating `self.head`/`self.tail` accordingly), decrement `size`. The removed node becomes unreachable once nothing points to it — no manual free needed.
+- [ ] **Step 5: Implement `clear`** — reset `self.head`/`self.tail` to `None` and `size` to `0`; every node becomes unreachable transitively.
+- [ ] **Step 6: Implement `reverse`** — build (or in-place relink) a new list with `prev`/`next` swapped at every node.
+- [ ] **Step 7: Add codegen tests** in `plum-wasm-codegen/tests/codegen_tests.rs` for each newly-implemented method, plus one test specifically proving a `Node.next: Option[Node]` field correctly becomes unreachable after `removeAt`/`clear` (per the spec's Testing section) — this can only be an indirect proof (e.g. removing many nodes in a loop and confirming the program still runs correctly and the list's `length`/traversal reflects the removal), since there's no direct "assert this was garbage collected" hook available from a compiled program's own execution.
+- [ ] **Step 8: Run `cargo test --workspace`.** Expected: 100% pass, including new tests.
+- [ ] **Step 9: Commit**
+```bash
+git add libs/std/list.plum plum-wasm-codegen/tests/codegen_tests.rs
+git commit -m "feat(libs/std): implement List's add/set/removeAt/remove/clear/reverse on wasm-gc"
+```
+---
+### Task 4: Final verification and README update
+**Files:** `README.md` (Known Gaps section)
+- [ ] **Step 1: `cargo build --workspace --all-targets` and `cargo test --workspace`.** Expected: 100% pass.
+- [ ] **Step 2: `cd tooling/tree-sitter-plum && npx --yes tree-sitter-cli test`** — unaffected by this plan (no grammar changes), confirm it's still 100% as a sanity check that nothing unrelated regressed.
+- [ ] **Step 3: Run `scripts/test-examples.sh`** (added in an earlier session) to confirm every `examples/*.plum` file still compiles and runs correctly through the real CLI end to end, not just the unit test suite.
+- [ ] **Step 4: Update README's "Known gaps" section** — the current entry "`libs/std`'s actual `List`/`Map` still don't fully compile ... `List`'s methods beyond `get`/`length` ... are still `todo`" is resolved by Task 3; remove or rewrite that bullet to reflect reality. Check whether `Map`'s own gap (references `Buffer`/`Stringable` trait-bounded dispatch, which `plum-checker` still doesn't process) is still accurate and leave that part as-is if so — don't overclaim `Map` fully works if trait dispatch still doesn't exist.
+- [ ] **Step 5: Commit**
+```bash
+git add README.md
+git commit -m "docs: update Known gaps for wasm-gc migration and List's new methods"
+```

plum-wasm-codegen/src/lib.rs CHANGED Viewed

@@ -15,8 +15,25 @@ const HEAP_BASE: u32 = 65536;
 /// String literal data (length-prefixed UTF-8 blobs) is laid out from here upward.
 const STRING_BASE: u32 = 8;
+/// 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>),
+}
 pub struct WasmModule {
-    types: Vec<FuncType>,
+    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)>,
@@ -35,6 +52,7 @@ impl WasmModule {
     pub fn new() -> Self {
         Self {
             types: Vec::new(),
+            next_type_idx: 0,
             imports: Vec::new(),
             functions: Vec::new(),
             exports: Vec::new(),
@@ -49,11 +67,26 @@ impl WasmModule {
     }
     pub fn addType(&mut self, params: &[ValType], results: &[ValType]) -> u32 {
-        let idx = self.types.len() as u32;
+        let idx = self.next_type_idx;
-        self.types.push(FuncType::new(params.iter().copied(), results.iter().copied()));
+        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));
@@ -108,8 +141,15 @@ impl WasmModule {
         // Type section
         let mut types = TypeSection::new();
-        for ft in &self.types {
+        for entry in &self.types {
+            match entry {
+                TypeEntry::Func(ft) => {
-            types.ty().function(ft.params().iter().copied(), ft.results().iter().copied());
+                    types.ty().function(ft.params().iter().copied(), ft.results().iter().copied());
+                }
+                TypeEntry::Rec(subtypes) => {
+                    types.ty().rec(subtypes.iter().cloned());
+                }
+            }
         }
         module.section(&types);
@@ -274,6 +314,11 @@ pub struct CompileCtx<'a> {
     /// Shared runtime helper `(n: i64) -> i32`: bump-allocates a new length-prefixed
     /// string 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 (Task 1 of
+    /// docs/superpowers/plans/2026-07-25-wasm-gc-migration.md) — populated but not
+    /// yet consumed by any codegen below; the bump allocator remains the real
+    /// representation until Task 2 lands.
+    pub gc_types: GcTypeRegistry,
 }
 /// Per-module state that accumulates as function bodies are compiled: the running
@@ -377,6 +422,170 @@ fn plumTypeToValtype(t: &PlumType) -> ValType {
     }
 }
+/// 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. Per Task 1 of docs/superpowers/plans/2026-07-25-wasm-gc-migration.md,
+/// this is currently populated but NOT YET consumed by construction/field-access/match
+/// codegen (that's Task 2) — its job right now is only to prove the type section itself
+/// is well-formed under the new representation, alongside the still-untouched
+/// bump-allocator codegen path.
+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,
+}
+/// 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::TNamed(name) => {
+            let idx = registry.class_type_idx.get(name)
+                .or_else(|| registry.enum_super_type_idx.get(name))
+                .unwrap_or_else(|| panic!("internal codegen error: unknown type '{}' in GC type registry", name));
+            ValType::Ref(RefType { nullable: true, heap_type: HeapType::Concrete(*idx) })
+        }
+        // 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,
+) -> GcTypeRegistry {
+    enum Slot {
+        Str,
+        Class(String),
+        EnumSuper,
+        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 {
+        if let ast::Item::Enum(e) = item {
+            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);
+        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,
+    };
+    // 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 },
+            }
+        }
+        Slot::EnumSuper => SubType {
+            is_final: false,
+            supertype_idx: None,
+            composite_type: CompositeType { inner: CompositeInnerType::Struct(StructType { fields: Vec::new().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));
+            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_ptr: I32`, then one param per
 /// declared param type, returning `ret`'s val type (or nothing for `Unit`).
@@ -438,6 +647,12 @@ pub fn compileSource(source: &ast::Source) -> Result<Vec<u8>, String> {
     Instruction::I32Const(HEAP_BASE as i32).encode(&mut bump_init);
     let bump_global = module.addGlobal(ValType::I32, true, &bump_init);
+    // Task 1 of the wasm-gc migration: declare the wasm-gc type section entries for
+    // every class/enum/Str up front. Purely additive right now — nothing below reads
+    // `gc_types` yet, so the bump-allocator codegen this function still emits is
+    // completely unaffected; this only proves the new type section is well-formed.
+    let gc_types = buildGcTypeRegistry(&mut module, source, &classes, &enum_variants);
     let mut func_ids: HashMap<String, u32> = HashMap::new();
     let mut func_sigs: HashMap<String, FuncSig> = HashMap::new();
     // Closure wasm signature -> function-type index, deduped so every closure/call site
@@ -604,7 +819,7 @@ pub fn compileSource(source: &ast::Source) -> Result<Vec<u8>, String> {
     let ctx = CompileCtx {
         func_ids, func_sigs, classes, methods, enum_variants, enum_params, global_env, bump_global,
         closures, closure_asts, closure_call_types, named_fn_values,
-        string_concat_func, int_to_string_func,
+        string_concat_func, int_to_string_func, gc_types,
     };
     let mut state = ModuleState { next_string_offset: next_static_offset, data_segments: named_fn_data_segments };

plum-wasm-codegen/tests/codegen_tests.rs CHANGED Viewed

@@ -11,6 +11,19 @@ fn parse(src: &str) -> plum_core::ast::Source {
     ap.parseSource(tree.root_node())
 }
+/// The wasm-gc migration (docs/superpowers/plans/2026-07-25-wasm-gc-migration.md)
+/// needs both `wasm_gc` and `wasm_function_references` enabled — confirmed
+/// empirically (see the `wasmtimeGcConfig*` tests below) rather than assumed from
+/// docs, since wasmtime's own doc comment on `Config::wasm_gc` warns its GC support
+/// is still in progress. Every test that instantiates/runs compiled output uses
+/// this shared engine so the whole harness stays on one config.
+fn gcEngine() -> wasmtime::Engine {
+    let mut config = wasmtime::Config::new();
+    config.wasm_gc(true);
+    config.wasm_function_references(true);
+    wasmtime::Engine::new(&config).expect("engine with GC config should construct")
+}
 #[test]
 fn compilesToValidWasm() {
     let src = "fun add(a: Int, b: Int) -> Int =\n  a + b\n";
@@ -328,7 +341,7 @@ fun main() -> Int =
 /// (via wasmparser, above) only proves the module is well-formed — it can't catch
 /// wrong *values*, so these tests actually execute the compiled output.
 fn runMain(bytes: &[u8]) -> i64 {
-    let engine = wasmtime::Engine::default();
+    let engine = gcEngine();
     let module = wasmtime::Module::new(&engine, bytes).expect("module should be loadable");
     let mut store = wasmtime::Store::new(&engine, ());
     let instance = wasmtime::Instance::new(&mut store, &module, &[]).expect("module should instantiate");
@@ -339,7 +352,7 @@ fn runMain(bytes: &[u8]) -> i64 {
 }
 fn runMainF64(bytes: &[u8]) -> f64 {
-    let engine = wasmtime::Engine::default();
+    let engine = gcEngine();
     let module = wasmtime::Module::new(&engine, bytes).expect("module should be loadable");
     let mut store = wasmtime::Store::new(&engine, ());
     let instance = wasmtime::Instance::new(&mut store, &module, &[]).expect("module should instantiate");
@@ -352,7 +365,7 @@ fn runMainF64(bytes: &[u8]) -> f64 {
 /// Runs a `() -> Str`-returning `main`, reading the length-prefixed
 /// `[len: u32][utf8 bytes]` string back out of the module's exported memory.
 fn runMainStr(bytes: &[u8]) -> String {
-    let engine = wasmtime::Engine::default();
+    let engine = gcEngine();
     let module = wasmtime::Module::new(&engine, bytes).expect("module should be loadable");
     let mut store = wasmtime::Store::new(&engine, ());
     let instance = wasmtime::Instance::new(&mut store, &module, &[]).expect("module should instantiate");
@@ -590,7 +603,7 @@ fun main() -> Int =
 ";
     let source = parse(src_trap);
     let bytes = compileSource(&source).expect("compile failed");
-    let engine = wasmtime::Engine::default();
+    let engine = gcEngine();
     let module = wasmtime::Module::new(&engine, &bytes).unwrap();
     let mut store = wasmtime::Store::new(&engine, ());
     let instance = wasmtime::Instance::new(&mut store, &module, &[]).unwrap();
@@ -611,7 +624,7 @@ fun main() -> Int =
 ";
     let source = parse(src);
     let bytes = compileSource(&source).expect("compile failed");
-    let engine = wasmtime::Engine::default();
+    let engine = gcEngine();
     let module = wasmtime::Module::new(&engine, &bytes).unwrap();
     let mut store = wasmtime::Store::new(&engine, ());
     let instance = wasmtime::Instance::new(&mut store, &module, &[]).unwrap();
@@ -1115,7 +1128,7 @@ fn wasmModuleWithATableElementValidatesAndCallIndirectWorks() {
     let result = wasmparser::validate(&bytes);
     assert!(result.is_ok(), "wasm validation failed: {:?}", result.err());
-    let engine = wasmtime::Engine::default();
+    let engine = gcEngine();
     let wasm_module = wasmtime::Module::new(&engine, &bytes).expect("module should be loadable");
     let mut store = wasmtime::Store::new(&engine, ());
     let instance = wasmtime::Instance::new(&mut store, &wasm_module, &[]).expect("module should instantiate");
@@ -1535,3 +1548,470 @@ fun main() -> Int =
     let bytes = compileSource(&source).expect("compile failed");
     assert_eq!(runMain(&bytes), 0);
 }
+#[test]
+fn wasmtimeGcConfigCanRunAHandEncodedGcModule() {
+    // Throwaway empirical check (plan Task 1, Step 1): confirm wasmtime 28's GC
+    // support actually works end to end before building a type-emitter on top of
+    // it. Hand-encodes the smallest possible module with one GC struct type and
+    // one function that does struct.new_default and returns it, bypassing plum
+    // entirely, so a failure here is unambiguously about wasmtime/wasm-encoder,
+    // not about anything plum-specific.
+    use wasm_encoder::*;
+    let mut module = Module::new();
+    let mut types = TypeSection::new();
+    // type 0: struct { i32 }
+    types.ty().struct_(vec![FieldType { element_type: StorageType::Val(ValType::I32), mutable: true }]);
+    // type 1: () -> (ref null 0)
+    let struct_ref = ValType::Ref(RefType { nullable: true, heap_type: HeapType::Concrete(0) });
+    types.ty().function(vec![], vec![struct_ref]);
+    module.section(&types);
+    let mut funcs = FunctionSection::new();
+    funcs.function(1);
+    module.section(&funcs);
+    let mut exports = ExportSection::new();
+    exports.export("main", ExportKind::Func, 0);
+    module.section(&exports);
+    let mut code = CodeSection::new();
+    let mut f = Function::new(vec![]);
+    f.instruction(&Instruction::StructNewDefault(0));
+    f.instruction(&Instruction::End);
+    code.function(&f);
+    module.section(&code);
+    let bytes = module.finish();
+    let mut config = wasmtime::Config::new();
+    config.wasm_gc(true);
+    config.wasm_function_references(true);
+    let engine = wasmtime::Engine::new(&config).expect("engine with GC config should construct");
+    let wasm_module = wasmtime::Module::new(&engine, &bytes).expect("hand-encoded GC module should be loadable");
+    let mut store = wasmtime::Store::new(&engine, ());
+    let instance = wasmtime::Instance::new(&mut store, &wasm_module, &[]).expect("module should instantiate");
+    let main = instance
+        .get_func(&mut store, "main")
+        .expect("main should be exported");
+    let mut results = [wasmtime::Val::I32(0)];
+    main.call(&mut store, &[], &mut results).expect("main should not trap");
+}
+#[test]
+fn wasmtimeGcConfigSupportsSubtypingRefTestAndNullableSelfReferentialFields() {
+    // Deeper empirical check: enum-variant subtyping (abstract supertype + concrete
+    // subtypes in one `rec` group), ref.test-based dispatch, ref.cast to narrow to a
+    // subtype, and a nullable field that references the struct's OWN type (the
+    // Node.next: Option[Node] shape List needs) — all in one hand-encoded module,
+    // bypassing plum entirely.
+    use wasm_encoder::*;
+    let mut module = Module::new();
+    let mut types = TypeSection::new();
+    // rec group: type 0 = abstract enum supertype (empty struct, non-final so it can
+    // be subtyped); type 1 = concrete "Some"-like subtype with one i32 payload field;
+    // type 2 = concrete "None"-like subtype (empty, no payload).
+    types.ty().rec(vec![
+        SubType {
+            is_final: false,
+            supertype_idx: None,
+            composite_type: CompositeType { inner: CompositeInnerType::Struct(StructType { fields: vec![].into() }), shared: false },
+        },
+        SubType {
+            is_final: true,
+            supertype_idx: Some(0),
+            composite_type: CompositeType {
+                inner: CompositeInnerType::Struct(StructType { fields: vec![
+                    FieldType { element_type: StorageType::Val(ValType::I32), mutable: false },
+                ].into() }),
+                shared: false,
+            },
+        },
+        SubType {
+            is_final: true,
+            supertype_idx: Some(0),
+            composite_type: CompositeType { inner: CompositeInnerType::Struct(StructType { fields: vec![].into() }), shared: false },
+        },
+    ]);
+    // type 3: a self-referential Node struct — { value: i32, next: ref null $Node }.
+    // Must be declared in its own rec group (or alone) referencing its own index (3)
+    // for the nullable self-reference to resolve.
+    types.ty().rec(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 { nullable: true, heap_type: HeapType::Concrete(3) })), mutable: true },
+                ].into() }),
+                shared: false,
+            },
+        },
+    ]);
+    // type 4: () -> i32 — constructs a "Some"-like subtype (type 1) holding 42,
+    // stores it as the supertype (type 0), ref.tests it against type 1, then
+    // ref.casts and struct.gets the payload back out. Also builds a 2-node linked
+    // list (type 3) and confirms unlinking (overwriting `next` with ref.null) and
+    // reading back the remaining node's value both work.
+    let super_ref = ValType::Ref(RefType { nullable: true, heap_type: HeapType::Concrete(0) });
+    types.ty().function(vec![], vec![ValType::I32]);
+    module.section(&types);
+    let mut funcs = FunctionSection::new();
+    funcs.function(4);
+    module.section(&funcs);
+    let mut exports = ExportSection::new();
+    exports.export("main", ExportKind::Func, 0);
+    module.section(&exports);
+    let mut code = CodeSection::new();
+    let mut f = Function::new(vec![(1, super_ref.clone()), (1, ValType::Ref(RefType { nullable: true, heap_type: HeapType::Concrete(3) }))]);
+    let locals_super = 0u32;
+    let locals_node = 1u32;
+    // local_super = Some(42) (as the supertype)
+    f.instruction(&Instruction::I32Const(42));
+    f.instruction(&Instruction::StructNew(1));
+    f.instruction(&Instruction::LocalSet(locals_super));
+    // local_node = Node { value: 1, next: null }
+    f.instruction(&Instruction::I32Const(1));
+    f.instruction(&Instruction::RefNull(HeapType::Concrete(3)));
+    f.instruction(&Instruction::StructNew(3));
+    f.instruction(&Instruction::LocalSet(locals_node));
+    // if ref.test(local_super, type 1) { result = ref.cast(local_super, type1).field0 } else { result = -1 }
+    f.instruction(&Instruction::LocalGet(locals_super));
+    f.instruction(&Instruction::RefTestNonNull(HeapType::Concrete(1)));
+    f.instruction(&Instruction::If(BlockType::Result(ValType::I32)));
+    f.instruction(&Instruction::LocalGet(locals_super));
+    f.instruction(&Instruction::RefCastNonNull(HeapType::Concrete(1)));
+    f.instruction(&Instruction::StructGet { struct_type_index: 1, field_index: 0 });
+    f.instruction(&Instruction::Else);
+    f.instruction(&Instruction::I32Const(-1));
+    f.instruction(&Instruction::End);
+    // unlink: local_node.next = ref.null (already null, but exercise the store path)
+    f.instruction(&Instruction::LocalGet(locals_node));
+    f.instruction(&Instruction::RefNull(HeapType::Concrete(3)));
+    f.instruction(&Instruction::StructSet { struct_type_index: 3, field_index: 1 });
+    // add local_node.value to the ref.test result and return
+    f.instruction(&Instruction::LocalGet(locals_node));
+    f.instruction(&Instruction::StructGet { struct_type_index: 3, field_index: 0 });
+    f.instruction(&Instruction::I32Add);
+    f.instruction(&Instruction::End);
+    code.function(&f);
+    module.section(&code);
+    let bytes = module.finish();
+    let mut config = wasmtime::Config::new();
+    config.wasm_gc(true);
+    config.wasm_function_references(true);
+    let engine = wasmtime::Engine::new(&config).expect("engine with GC config should construct");
+    let wasm_module = wasmtime::Module::new(&engine, &bytes).unwrap_or_else(|e| panic!("module should be loadable: {e}"));
+    let mut store = wasmtime::Store::new(&engine, ());
+    let instance = wasmtime::Instance::new(&mut store, &wasm_module, &[]).expect("module should instantiate");
+    let main = instance
+        .get_typed_func::<(), i32>(&mut store, "main")
+        .expect("main should have signature () -> i32");
+    let result = main.call(&mut store, ()).expect("main should not trap");
+    assert_eq!(result, 43, "expected ref.test/ref.cast payload (42) + node.value (1) = 43");
+}
+#[test]
+fn wasmtimeGcConfigAllowsStructNewInGlobalConstExpr() {
+    // Decision 2 of the wasm-gc migration plan pre-allocates payload-free enum
+    // variants (True/False/None/...) once as globals. Confirm a global's
+    // initializer expression can directly use struct.new (not just i32.const/
+    // ref.null), or the plan needs a `start` function fallback instead.
+    use wasm_encoder::*;
+    let mut module = Module::new();
+    let mut types = TypeSection::new();
+    types.ty().struct_(vec![FieldType { element_type: StorageType::Val(ValType::I32), mutable: false }]);
+    types.ty().function(vec![], vec![ValType::I32]);
+    module.section(&types);
+    let mut funcs = FunctionSection::new();
+    funcs.function(1);
+    module.section(&funcs);
+    let mut globals = GlobalSection::new();
+    let struct_ref_ty = ValType::Ref(RefType { nullable: true, heap_type: HeapType::Concrete(0) });
+    let mut init = Vec::new();
+    Instruction::I32Const(7).encode(&mut init);
+    Instruction::StructNew(0).encode(&mut init);
+    Instruction::End.encode(&mut init);
+    globals.global(
+        GlobalType { val_type: struct_ref_ty, mutable: false, shared: false },
+        &ConstExpr::raw(init),
+    );
+    module.section(&globals);
+    let mut exports = ExportSection::new();
+    exports.export("main", ExportKind::Func, 0);
+    module.section(&exports);
+    let mut code = CodeSection::new();
+    let mut f = Function::new(vec![]);
+    f.instruction(&Instruction::GlobalGet(0));
+    f.instruction(&Instruction::StructGet { struct_type_index: 0, field_index: 0 });
+    f.instruction(&Instruction::End);
+    code.function(&f);
+    module.section(&code);
+    let bytes = module.finish();
+    let mut config = wasmtime::Config::new();
+    config.wasm_gc(true);
+    config.wasm_function_references(true);
+    let engine = wasmtime::Engine::new(&config).expect("engine with GC config should construct");
+    let wasm_module = match wasmtime::Module::new(&engine, &bytes) {
+        Ok(m) => m,
+        Err(e) => {
+            println!("struct.new in a global const-expr is NOT supported by this wasmtime/config: {e}");
+            println!("plan implication: Task 2 Step 2 (2a) must use a `start` function instead of a const global initializer.");
+            return;
+        }
+    };
+    let mut store = wasmtime::Store::new(&engine, ());
+    let instance = wasmtime::Instance::new(&mut store, &wasm_module, &[]).expect("module should instantiate");
+    let main = instance.get_typed_func::<(), i32>(&mut store, "main").expect("main should have signature () -> i32");
+    let result = main.call(&mut store, ()).expect("main should not trap");
+    assert_eq!(result, 7);
+    println!("struct.new IS supported directly in a global const-expr initializer.");
+}
+#[test]
+fn wasmtimeGcConfigSupportsStartFunctionInitializingGcGlobals() {
+    // Follow-up to the previous test: struct.new isn't allowed in a global
+    // const-expr, so confirm the `start` function fallback works instead —
+    // a mutable global initialized to ref.null, populated by struct.new inside
+    // a `start` function that runs once at instantiation before any export.
+    use wasm_encoder::*;
+    let mut module = Module::new();
+    let mut types = TypeSection::new();
+    types.ty().struct_(vec![FieldType { element_type: StorageType::Val(ValType::I32), mutable: false }]);
+    types.ty().function(vec![], vec![]); // start fn: () -> ()
+    types.ty().function(vec![], vec![ValType::I32]); // main: () -> i32
+    module.section(&types);
+    let mut funcs = FunctionSection::new();
+    funcs.function(1); // func 0: start
+    funcs.function(2); // func 1: main
+    module.section(&funcs);
+    let mut globals = GlobalSection::new();
+    let struct_ref_ty = ValType::Ref(RefType { nullable: true, heap_type: HeapType::Concrete(0) });
+    globals.global(
+        GlobalType { val_type: struct_ref_ty.clone(), mutable: true, shared: false },
+        &ConstExpr::ref_null(HeapType::Concrete(0)),
+    );
+    module.section(&globals);
+    let mut exports = ExportSection::new();
+    exports.export("main", ExportKind::Func, 1);
+    module.section(&exports);
+    let start = StartSection { function_index: 0 };
+    module.section(&start);
+    let mut code = CodeSection::new();
+    let mut start_fn = Function::new(vec![]);
+    start_fn.instruction(&Instruction::I32Const(99));
+    start_fn.instruction(&Instruction::StructNew(0));
+    start_fn.instruction(&Instruction::GlobalSet(0));
+    start_fn.instruction(&Instruction::End);
+    code.function(&start_fn);
+    let mut main_fn = Function::new(vec![]);
+    main_fn.instruction(&Instruction::GlobalGet(0));
+    main_fn.instruction(&Instruction::StructGet { struct_type_index: 0, field_index: 0 });
+    main_fn.instruction(&Instruction::End);
+    code.function(&main_fn);
+    module.section(&code);
+    let bytes = module.finish();
+    let mut config = wasmtime::Config::new();
+    config.wasm_gc(true);
+    config.wasm_function_references(true);
+    let engine = wasmtime::Engine::new(&config).expect("engine with GC config should construct");
+    let wasm_module = wasmtime::Module::new(&engine, &bytes).unwrap_or_else(|e| panic!("module should be loadable: {e}"));
+    let mut store = wasmtime::Store::new(&engine, ());
+    let instance = wasmtime::Instance::new(&mut store, &wasm_module, &[]).expect("module should instantiate (start fn should run automatically)");
+    let main = instance.get_typed_func::<(), i32>(&mut store, "main").expect("main should have signature () -> i32");
+    let result = main.call(&mut store, ()).expect("main should not trap");
+    assert_eq!(result, 99, "start fn should have populated the global before main ran");
+}
+#[test]
+fn wasmtimeGcConfigSupportsArrayNewDataFromPassiveSegmentWithNoMemorySection() {
+    // Decision 4 of the wasm-gc migration plan: static string data lives in a
+    // PASSIVE data segment (no active memory offset), consumed via array.new_data
+    // — confirming this needs no `memory` section in the module at all, which is
+    // what lets the whole memory section disappear once bump allocation is retired.
+    use wasm_encoder::*;
+    let mut module = Module::new();
+    let mut types = TypeSection::new();
+    types.ty().array(&StorageType::I8, false);
+    let arr_ref = ValType::Ref(RefType { nullable: true, heap_type: HeapType::Concrete(0) });
+    types.ty().function(vec![], vec![ValType::I32]);
+    module.section(&types);
+    let mut funcs = FunctionSection::new();
+    funcs.function(1);
+    module.section(&funcs);
+    let mut exports = ExportSection::new();
+    exports.export("main", ExportKind::Func, 0);
+    module.section(&exports);
+    // Required whenever the module uses array.new_data/memory.init/data.drop —
+    // the validator needs the passive-segment count before the code section.
+    module.section(&DataCountSection { count: 1 });
+    let mut code = CodeSection::new();
+    let mut f = Function::new(vec![(1, arr_ref)]);
+    // local 0 = array.new_data(type 0, data segment 0) with offset=0, len=5 ("hello")
+    f.instruction(&Instruction::I32Const(0)); // data offset
+    f.instruction(&Instruction::I32Const(5)); // length
+    f.instruction(&Instruction::ArrayNewData { array_type_index: 0, array_data_index: 0 });
+    f.instruction(&Instruction::LocalSet(0));
+    // return array.get(local0, 0) — the byte 'h' = 104
+    f.instruction(&Instruction::LocalGet(0));
+    f.instruction(&Instruction::I32Const(0));
+    f.instruction(&Instruction::ArrayGetU(0));
+    f.instruction(&Instruction::End);
+    code.function(&f);
+    module.section(&code);
+    // NOTE: deliberately no MemorySection at all.
+    let mut data = DataSection::new();
+    data.passive(b"hello".iter().copied());
+    module.section(&data);
+    let bytes = module.finish();
+    let mut config = wasmtime::Config::new();
+    config.wasm_gc(true);
+    config.wasm_function_references(true);
+    let engine = wasmtime::Engine::new(&config).expect("engine with GC config should construct");
+    let wasm_module = wasmtime::Module::new(&engine, &bytes).unwrap_or_else(|e| panic!("module with no memory section + passive data should be loadable: {e}"));
+    let mut store = wasmtime::Store::new(&engine, ());
+    let instance = wasmtime::Instance::new(&mut store, &wasm_module, &[]).expect("module should instantiate");
+    let main = instance.get_typed_func::<(), i32>(&mut store, "main").expect("main should have signature () -> i32");
+    let result = main.call(&mut store, ()).expect("main should not trap");
+    assert_eq!(result, b'h' as i32);
+}
+#[test]
+fn wasmtimeGcConfigSupportsWideningConcreteStructRefToAnyrefAndCastingBack() {
+    // Decision 3 of the wasm-gc migration plan: closure env pointers are `anyref`
+    // in the shared call_indirect signature, with each closure's body ref.cast-ing
+    // back to its own concrete env struct type. Confirm a concrete struct ref can
+    // be stored where anyref is expected (implicit widening, no instruction needed)
+    // and RefCastNonNull(Concrete(_)) recovers the concrete type correctly.
+    use wasm_encoder::*;
+    let mut module = Module::new();
+    let mut types = TypeSection::new();
+    types.ty().struct_(vec![FieldType { element_type: StorageType::Val(ValType::I32), mutable: false }]);
+    // "identity-ish" function: (anyref) -> i32, casts back to concrete type 0 and reads field 0.
+    types.ty().function(vec![ValType::Ref(RefType::ANYREF)], vec![ValType::I32]);
+    // main: () -> i32, builds a concrete struct, passes it (widened) to func 1.
+    types.ty().function(vec![], vec![ValType::I32]);
+    module.section(&types);
+    let mut funcs = FunctionSection::new();
+    funcs.function(1); // func 0: the anyref-accepting fn
+    funcs.function(2); // func 1: main
+    module.section(&funcs);
+    let mut exports = ExportSection::new();
+    exports.export("main", ExportKind::Func, 1);
+    module.section(&exports);
+    let mut code = CodeSection::new();
+    let mut cast_fn = Function::new(vec![]);
+    cast_fn.instruction(&Instruction::LocalGet(0));
+    cast_fn.instruction(&Instruction::RefCastNonNull(HeapType::Concrete(0)));
+    cast_fn.instruction(&Instruction::StructGet { struct_type_index: 0, field_index: 0 });
+    cast_fn.instruction(&Instruction::End);
+    code.function(&cast_fn);
+    let mut main_fn = Function::new(vec![]);
+    main_fn.instruction(&Instruction::I32Const(55));
+    main_fn.instruction(&Instruction::StructNew(0)); // pushes (ref 0) — implicitly a subtype of anyref
+    main_fn.instruction(&Instruction::Call(0)); // call expects anyref param — implicit widening at the call site
+    main_fn.instruction(&Instruction::End);
+    code.function(&main_fn);
+    module.section(&code);
+    let bytes = module.finish();
+    let mut config = wasmtime::Config::new();
+    config.wasm_gc(true);
+    config.wasm_function_references(true);
+    let engine = wasmtime::Engine::new(&config).expect("engine with GC config should construct");
+    let wasm_module = wasmtime::Module::new(&engine, &bytes).unwrap_or_else(|e| panic!("module should be loadable: {e}"));
+    let mut store = wasmtime::Store::new(&engine, ());
+    let instance = wasmtime::Instance::new(&mut store, &wasm_module, &[]).expect("module should instantiate");
+    let main = instance.get_typed_func::<(), i32>(&mut store, "main").expect("main should have signature () -> i32");
+    let result = main.call(&mut store, ()).expect("main should not trap");
+    assert_eq!(result, 55, "concrete struct ref should widen to anyref implicitly and cast back correctly");
+}
+#[test]
+fn gcTypeRegistryProducesAWellFormedTypeSectionAlongsideBumpAllocatorCodegen() {
+    // Task 1 Step 5 of the wasm-gc migration plan: the new (currently unconsumed)
+    // wasm-gc type registry declares a well-formed type section — a struct type per
+    // class, a supertype+subtypes set per enum (including the built-in Bool), and a
+    // shared Str array type — even though every OTHER part of this compiled module
+    // still uses the old bump-allocator representation. Exercises a class, an enum
+    // with both a payload and a payload-free variant, and Str, so all three GC type
+    // shapes actually get emitted.
+    let src = "\
+type Cat =
+  name: Str
+  age: Int
+enum Option =
+  | Some[Int]
+  | None
+fun main() -> Int =
+  c = Cat(name: \"x\", age: 7)
+  c.age
+";
+    let source = parse(src);
+    let bytes = compileSource(&source).expect("compile failed");
+    let result = wasmparser::validate(&bytes);
+    assert!(result.is_ok(), "wasm validation failed: {:?}", result.err());
+    // And the still-untouched bump-allocator codegen must still actually run correctly —
+    // this task is purely additive, nothing behavioral should have changed.
+    assert_eq!(runMain(&bytes), 7);
+}

plum-wasm-codegen/tests/examples_test.rs CHANGED Viewed

@@ -17,6 +17,15 @@ fn parseFile(name: &str) -> plum_core::ast::Source {
     ap.parseSource(tree.root_node())
 }
+/// See the identically-named helper in codegen_tests.rs for why both features
+/// are needed (part of the wasm-gc migration, docs/superpowers/plans/2026-07-25-wasm-gc-migration.md).
+fn gcEngine() -> wasmtime::Engine {
+    let mut config = wasmtime::Config::new();
+    config.wasm_gc(true);
+    config.wasm_function_references(true);
+    wasmtime::Engine::new(&config).expect("engine with GC config should construct")
+}
 fn assertCompiles(name: &str) -> Vec<u8> {
     let source = parseFile(name);
     let bytes = compileSource(&source).unwrap_or_else(|e| panic!("{} failed to compile: {}", name, e));
@@ -54,7 +63,7 @@ fn typesCompiles() {
 fn methodsCompilesAndRunsCorrectly() {
     let bytes = assertCompiles("methods.plum");
-    let engine = wasmtime::Engine::default();
+    let engine = gcEngine();
     let module = wasmtime::Module::new(&engine, &bytes).expect("module should be loadable");
     let mut store = wasmtime::Store::new(&engine, ());
     let instance = wasmtime::Instance::new(&mut store, &module, &[]).expect("module should instantiate");
@@ -72,7 +81,7 @@ fn methodsCompilesAndRunsCorrectly() {
 #[test]
 fn matchExampleCompilesAndRunsCorrectly() {
     let bytes = assertCompiles("match.plum");
-    let engine = wasmtime::Engine::default();
+    let engine = gcEngine();
     let module = wasmtime::Module::new(&engine, &bytes).expect("module should be loadable");
     let mut store = wasmtime::Store::new(&engine, ());
     let instance = wasmtime::Instance::new(&mut store, &module, &[]).expect("module should instantiate");
@@ -89,7 +98,7 @@ fn matchExampleCompilesAndRunsCorrectly() {
 #[test]
 fn closuresExampleCompilesAndRunsCorrectly() {
     let bytes = assertCompiles("closures.plum");
-    let engine = wasmtime::Engine::default();
+    let engine = gcEngine();
     let module = wasmtime::Module::new(&engine, &bytes).expect("module should be loadable");
     let mut store = wasmtime::Store::new(&engine, ());
     let instance = wasmtime::Instance::new(&mut store, &module, &[]).expect("module should instantiate");