plum

# Bracket Generics Syntax — Design Spec

## Goal

Migrate Plum's generic-type syntax from parenthesized, lowercase-letter declarations

(`type Node(a) = ...`, `a`/`b`/`c`/`d` only) to bracketed, uppercase-letter declarations

(`type Node[T] = ...`, any single uppercase letter), and apply the same bracket

convention everywhere a generic type parameter appears — declarations, field types,

return types, and enum variant payloads. Parens are reserved for value-level argument

lists (function calls, class/enum constructors) and trait "implements" lists.

This is a pure syntax migration: it does not change generics semantics, monomorphization

behavior, or add new type-system features. `libs/std/list.plum` already has one

class (`Node`) partially migrated (`type Node[T] =`, uncommitted) which is what

prompted this spec — the rest of the language needs to catch up to (and formalize)

that shape.

## Current state (pre-migration)

- **Declaration syntax**: `type Foo(a) =`, `type Foo(Trait)(a: Trait) =`,

  `trait Foo(a: Bound) =` — parens, implements-list before generics-list.

- **Generic parameter names**: exactly one of the 4 hardcoded lowercase letters

  `a`, `b`, `c`, `d` (`tooling/tree-sitter-plum/grammar.js`'s `generic` rule is

  `choice($.a, $.b, $.c, $.d)`, literal tokens). No 5th letter is possible today.

- **Usage sites**: `type` (field types, generic-arg lists like `Option[Node]` /

  `Option(a)`) already accepts *both* `[...]` and `(...)` — this is the one place

  ahead of the rest of the grammar. `return_type` does NOT reuse this rule; it has

  its own paren-only `generics` field, so `-> Option[Node]` doesn't currently parse

  as a return type, only `-> Option(a)` does (existing asymmetry, fixed by this

  migration — see below).

- **Enum variant payloads**: `| Some(a)`, `| Ok(a)` — parens, sharing surface syntax

  with a value-level constructor call.

- **Method receiver annotation** (`get<List>(self, ...)`) is a separate, unrelated

  mechanism (`fn_type: "<" type_identifier ">"`) — it names which class/enum a method

  dispatches on, never introduces or binds a type parameter, and is untouched by

  this migration.

- **`plum-checker/src/monomorphize.rs`**'s `is_generic_param_name` — the single

  centralized check used everywhere a `Fn`'s or `Enum`'s generic parameters are

  *inferred* (`Class`/`Trait` instead read an explicit `generics` list off the AST)

  — currently defines "generic parameter name" as "exactly one ASCII lowercase

  letter."

## New syntax

### Lexical rule

- `generic` becomes a single uppercase ASCII letter: `/[A-Z]/`. Any letter A-Z is a

  valid generic name now (no more 4-letter cap).

- `type_identifier` becomes `/[A-Z][a-zA-Z0-9]+/` — **2 or more characters**. This

  is the key disambiguating change: today's `/[A-Z][a-zA-Z0-9]*/` (0-or-more) also

  matches a single letter, which would collide with the new uppercase `generic`

  token. Requiring 2+ characters means concrete type names (`List`, `Option`, `Node`,

  ...) and generic parameter names (`T`, `U`, `K`, `V`, ...) are lexically disjoint

  by construction — no grammar conflict, no context-sensitive lookahead needed.

- **Trade-off (confirmed with user):** single-letter type names (`T`, `A`, `X`, ...)

  become permanently illegal as concrete type names. Acceptable since every real

  type in this codebase is a multi-letter word.

### Declarations

```

type Foo[T] =

  value: T

type List[T: Stringable](Stringable) =

  head: Option[Node]

  ...

trait Comparable[T: Ord] =

  compareTo(other: T) -> Int

```

- `generics` rule: `"[" commaSep1(generic_type) "]"` (was `"(" ... ")"`).

- Field order swaps: **generics-with-bounds come first, implements-list comes

  second** — `type List[T: Stringable](Stringable) =`, not the old

  implements-then-generics order. The parser's "implements = leading

  `type_identifier`s before the first field" derivation needs updating for the new

  field order.

- `generic_type` (the bound syntax, `T: Bound`) is unchanged structurally — only

  the enclosing bracket and the letter case change.

### Usage sites (field types, return types, generic-arg lists)

```

type Node[T] =

  value: T

  prev: Option[Node]

  next: Option[Node]

get<List>(self, i: Int) -> Option[T] =

  ...

```

- `type`'s existing dual bracket/paren acceptance collapses to bracket-only.

- `return_type` stops being its own paren-only rule with its own

  `Vec<GenericParam>` AST shape (`ast.rs`'s `ReturnType.generics`) and instead

  reuses `$.type` directly, matching `Type.generics: Vec<Type>`. This fixes the

  existing `Type` vs `ReturnType` asymmetry as a side effect of the migration

  rather than carrying it forward.

### Enum variant payloads

```

enum Option[T] =

  | Some[T]

  | None

```

- `enum_field`'s payload list moves from `"(" commaSep1(choice(type_identifier,

  generic)) ")"` to the bracketed form, for full consistency with every other

  generic-type appearance in the language.

## What does NOT change

- Method receiver annotation `get<List>(self, ...)` — angle brackets, orthogonal

  mechanism, untouched.

- Value-level constructor/call parens (`Ok(5)`, `List(head: None, ...)`,

  `add(1, 2, 3)`) — parens stay parens; this migration only touches type-level

  generic syntax.

- Trait "implements" lists (`(Stringable)` in `type List[T: Stringable](Stringable)

  =`, `type Str(Comparable, Stringable, ...) =`) — stay parenthesized; they're a

  list of trait names being implemented, not a generic-parameter declaration.

- Generics semantics, inference, monomorphization behavior, bounds checking — all

  unchanged. This is syntax only.

## Implementation impact by layer

- **`tooling/tree-sitter-plum/grammar.js`**: `generic`, `generics`, `type_identifier`,

  `class`, `trait`, `return_type`, `enum_field` rules change per above. Regenerate

  the parser. Update corpus tests: `test/corpus/type.txt`, `trait.txt`, `enum.txt`,

  `function.txt`.

- **`plum-core/src/ast.rs`**: `ReturnType` drops its separate `generics: Vec<GenericParam>`

  field/shape, reuses `Type`'s representation (`Vec<Type>`) instead.

- **`plum-core/src/parser.rs`**: `parse_generics_field` and `parse_enum_variant`

  currently match node `kind()` against the literal set `"a"|"b"|"c"|"d"`; since

  `generic` becomes one regex-based token, this collapses to a single node-kind

  check. `parse_class`'s implements-list derivation (currently "leading

  `type_identifier`s before the first field") needs updating for the new

  generics-then-implements field order. `parse_return_type` is simplified to just

  call the same logic as `parse_type`.

- **`plum-checker/src/monomorphize.rs`**: `is_generic_param_name` flips from

  "single ASCII lowercase letter" to "single ASCII uppercase letter." This is the

  only definition site (confirmed, nothing else re-derives the convention), so this

  is a one-line-condition change plus updating its doc comment.

- **`plum-wasm-codegen`**: no source changes — codegen only ever sees fully

  monomorphized (generic-free) AST. Only test fixtures change.

- **Stdlib** (`libs/std/`): `list.plum` (finish what `Node[T]` started — `List`,

  every method signature), `map.plum` (`Pair[K, V]`, `Map[K, V]`, method

  signatures), `option.plum` (`Some[T]`), `result.plum` (`Ok[T]`, `Err[E]`).

  Per-slot letter choices favor readability over always defaulting to `T`

  (`K`/`V` for maps, `T`/`U` for a two-param list/function context, `E` for error

  types) where a clearer letter fits.

- **Examples** (`examples/`): `types.plum` (`Box(a)` → `Box[T]`, `Comparable(a: Ord)`

  → `Comparable[T: Ord]`).

- **Tests**: `plum-checker/tests/checker_tests.rs`, `plum-checker/tests/monomorphize_tests.rs`,

  `plum-wasm-codegen/tests/codegen_tests.rs` — embedded `.plum` source strings

  updated to new syntax.

- **Design docs**: `docs/superpowers/specs/2026-07-20-generics-monomorphization-design.md`

  and `2026-07-20-generic-enum-multi-instantiation-design.md` explicitly document

  the *old* syntax as canonical (e.g. "a, b, c, d — the grammar's only legal

  generic-parameter spelling"). These are historical records of already-shipped

  work and are **not** rewritten by this migration — readers should treat them as

  describing pre-migration syntax.

## Known conflict: `2026-07-24-list-methods.md` plan

The untracked implementation plan `docs/superpowers/plans/2026-07-24-list-methods.md`

(and its spec) is written entirely in the old syntax (`type Node(a) =`) and has not

been executed yet. It also predates `list.plum`'s current on-disk state (which

already has `Node[T]` on line 6), so it's already stale independent of this

migration. This plan should be treated as **blocked** — it needs rewriting against

both the new bracket syntax and the current `list.plum` contents before anyone

executes it. This migration does not rewrite that plan; that's a separate,

follow-up piece of work.

## Testing strategy

- Update tree-sitter corpus tests first (grammar-level), verify `tree-sitter test`

  passes against the new syntax.

- Update `plum-core` parser tests if any cover generics shape (survey found none

  currently do — `parser_test.rs`/`formatter_test.rs` have zero matches — so this

  migration is a good opportunity to add minimal coverage of the new bracket shape).

- Update `plum-checker`'s `checker_tests.rs` and `monomorphize_tests.rs` fixtures.

- Update `plum-wasm-codegen`'s `codegen_tests.rs` fixtures.

- Update stdlib and examples, confirm `cargo test --workspace` passes throughout.

- No behavior changes are expected — every currently-passing test should still pass

  with only its embedded source syntax rewritten, and results (assertions) unchanged.