plum

# Closures (`|params| body`)

## Problem

`closure` (`|params| body`) already exists as a tree-sitter grammar rule but is unreachable from
any parse path — it's referenced only in a comment inside `expression`'s choice list. There is
also no function-value type annotation syntax at all (something like `cb: fn(v: a) -> Bool`,
as used in the aspirational `libs/std/list.plum`, doesn't parse today). Without closures, any
higher-order method (`each`, `map`, `filter`, `reduce`, `sort`, ...) on a future `List`/`Map` has
no way to accept a callback, and `list.plum`'s actual usage (`this.each() |v| { res.write(v.to_str(),
sep) }`, capturing `res`/`sep` from the enclosing method) can't be expressed at all.

## Scope

Full, capturing closures — not just non-capturing function values. `list.plum`'s real usage reads
enclosing-scope variables from inside a closure literal, so a "closures" feature that can't
capture wouldn't actually unblock the motivating use case.

**Capture semantics: snapshot by value**, not live/shared mutable capture. A captured variable's
*current value* is copied into the closure's environment at the moment the closure literal is
evaluated; a later mutation to that variable in the enclosing scope is not visible inside an
already-created closure. This is simpler (no heap-boxed shared cells needed for ordinary locals)
and matches every known real usage (reading `res`/`sep`, not reassigning them from inside the
closure). Live/shared capture is explicitly out of scope — flagged here as a real semantic choice,
not an oversight, in case a future use case needs it.

**Call syntax: ordinary-argument only**, not trailing-closure syntax. `list.plum`'s draft usage
(`this.each() |v| { ... }` — the closure attached *after* a completed call, Ruby/Kotlin-style) is a
distinct, more elaborate grammar feature (a call expression optionally followed by a closure) than
a closure used as a normal expression. Since `list.plum` itself gets rewritten to standard syntax
in a later, separate follow-up, this feature only needs to support a closure passed as an ordinary
call argument — `each(|v| ...)` — not the trailing-block form.

## Design

### 1. Grammar (`tooling/tree-sitter-plum`)

- Uncomment `$.closure` in `expression`'s choice list (the rule itself — `"|" params "|" body` —
  already exists and needs no changes).
- Add a new function-value type rule for param type annotations, using **positional types only**
  (no param names in the annotation — types don't need names, and this stays consistent with the
  existing type-list convention `List(a)`/`Pair(a, b)`): `fn(Int) -> Bool`, `fn(a) -> b`. Usable
  wherever a param type currently appears (`each(cb: fn(a))`).

### 2. AST (`plum-core`)

- New `ast::Closure { params: Vec<String>, body: Block }`, added as `Expr::Closure(Box<Closure>)`.
- New `ast::ParamType::Fn(Vec<Type>, Option<Box<Type>>)` variant (param types, param positions
  only — a class field storing a callback value is out of scope, not needed by any current
  example or by `list.plum`'s actual usage, which only ever passes closures as call arguments).

### 3. Checker (`plum-checker`)

- `PlumType::TFun(Vec<PlumType>, Box<PlumType>)` already exists and models a closure's type
  directly — no new `PlumType` variant needed.
- `infer_expr`'s new `Closure` arm: bind each closure param to a fresh `TVar` (matching this
  checker's existing permissive style — it already never really unifies generic parameters, just
  accepts them), infer the body against that environment, return `TFun(param_types, body_type)`.
- Calling a closure-typed parameter by name (`cb(x)`) already type-checks via the **existing**
  `FnCall` inference path unmodified — `lookup(env, &call.name)` resolves any `TFun`-typed binding
  in scope, regardless of whether it came from a top-level function or a local closure-typed
  param. No changes needed there.

### 4. Codegen (`plum-wasm-codegen`)

This is the substantial part — wasm has no closures natively, so it needs:

- **New wasm sections**: a function table and an elements segment. `WasmModule` needs
  `add_table`/element-segment support, which doesn't exist yet.
- **Compiling a closure literal**: every closure literal becomes its own real wasm function,
  registered as a table element, with an **implicit first parameter** — the boxed
  captured-environment pointer — exactly mirroring how a method already receives `self` as an
  implicit first parameter. Inside the closure's compiled body, each captured variable is loaded
  from a fixed offset within that env struct (same load mechanics already used for class fields).
- **Free-variable analysis**: at the point a closure literal appears in source, walk its body and
  collect every referenced name that is NOT one of the closure's own declared params, a global, or
  a function name — these are the captured variables, snapshotted by value.
- **Constructing the closure value**: at the closure literal's site, bump-allocate an env struct
  sized to hold the captured variables' current values (same bump-allocator convention as class
  instances), then bump-allocate a small `{table_index: i32, env_pointer: i32}` pair. The pointer
  to that pair **is** the closure's runtime value — a single `i32`, consistent with every other
  reference-shaped value in this compiler (class instances, payload-carrying enum variants).
- **Calling a closure value**: load `table_index` and `env_pointer` from the pointer, push
  `env_pointer` then the real call arguments, then `call_indirect`. The wasm type index for
  `call_indirect` is resolved from the **caller's** own already-concrete (monomorphized) call
  site — a closure's internal capture layout is opaque to its caller, so calling a higher-order
  function like `each` needs no new monomorphization mechanism: `each`'s own concrete
  instantiation (via the existing generics pass) already fixes what signature any closure passed
  to it must have, and the checker already enforces that at the call site.

## Testing plan

- **Grammar**: corpus tests for a closure literal parsing in expression position, and a
  `fn(...)`-typed param annotation parsing correctly (both bracket-free positional-type forms:
  `fn(Int) -> Bool`, `fn(a) -> b`).
- **Checker**: a closure's inferred `TFun` type flows correctly into a `TFun`-typed binding;
  calling a closure-typed param type-checks via the unmodified `FnCall` path.
- **Codegen** (compiled and executed via `wasmtime`, matching existing style):
  - A non-capturing closure passed to a function and called.
  - A closure capturing one enclosing local, called after that local's value has changed in the
    enclosing scope — proving the capture is a value snapshot at creation time, not a live
    reference (the closure must see the OLD value, not the new one).
  - A closure passed through an already-generic higher-order function (proving the two features
    compose — the outer function is monomorphized per its own generic param as usual, and any
    closure passed to it is called correctly via `call_indirect` regardless).
- **Examples**: a minimal, real end-to-end usage (e.g. a small `each`-like helper function taking
  a `fn(a)` callback, called with both a non-capturing and a capturing closure).

## Out of scope

- A class field storing a closure value.
- Live/shared mutable capture (a closure seeing a later mutation to a captured variable) — see
  "Capture semantics" above; this is a deliberate simplification, not a deferred requirement.
- Multiple closures with genuinely different captured-variable layouts needing different wasm
  function *signatures* at the same `call_indirect` site — not expected to arise given the design
  (the env pointer is always a single opaque `i32` regardless of what it points to), but noted as
  an edge to watch during implementation.
- Rewriting `libs/std/list.plum`/`map.plum` to actually use this — a separate, subsequent
  follow-up once closures exist.