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.