plum

# Enum Discriminant Values — Design Spec

## Goal

Let an enum declare one or more shared, uniformly-typed fields that every
variant supplies a concrete value for, readable via ordinary field access
(`self.n`) regardless of which variant a given instance actually is:

```
enum Step(n: Int) =
  | READ_MIN_OCCURANCES(0)
  | READ_MAX_OCCURANCES(1)
  | READ_CHAR_TO_COUNT(2)
  | COUNT_OCCURANCES(3)
```

Here every `Step` value carries an `Int` field `n`; `READ_MIN_OCCURANCES.n`
(or `self.n` inside a method) reads `0` without needing a `match`. This is
different from today's per-variant payload (`Some(a)`/`Ok(a)`), where each
variant's payload has a different shape and can only be read by destructuring
via `match`.

## Non-goals

- No mixing of enum-level discriminant params with today's per-variant
  generic-type payload (`| Some[T]`) in the same enum — an enum is either
  a "discriminant enum" (this feature) or an ordinary/generic enum
  (today's feature), not both, for v1. If a real use case for combining them
  shows up later, that's a follow-up.
- No change to how ordinary enums (`Option`, `Result`, `Bool`, `Color`, ...)
  are declared, checked, or compiled — this is purely additive.
- No automatic derivation of a discriminant from declaration order (that's
  `plum-checker`'s existing internal *tag* numbering, which already exists
  and is unrelated — see Current State). This feature is about a
  user-declared, user-typed, user-readable field, not the internal tag.

## Current state (relevant constraints found during design)

This is the key architectural fact the design has to work around:

- **Payload-free variants are bare integers today, not heap values.** A
  nullary variant like `None`/`True`/`Red` compiles to a plain `i32.const`
  with **no heap allocation** (`plum-wasm-codegen`'s
  `compile_variant_construction`: `if field_types.is_empty() { return
  I32Const(tag) }`). This is a real optimization the checker/codegen rely on
  elsewhere (pattern-match codegen explicitly branches on "is this variant a
  small int or a heap pointer").
- **Payload variants are heap-allocated as `[tag: i32][field0][field1]...`**,
  each slot at an 8-byte stride, sized independently per variant (no
  "widest variant" padding).
- **Field access (`self.field`) is class-only today.** It requires the
  receiver's type to resolve to a `Class` in `ClassEnv`, looks up the
  field's positional index, and loads at `field_idx * 8` from the class's
  heap pointer. Enums have no entry in `ClassEnv` and are never consulted
  by this code path today.
- **A bare variant reference used as a value** (`None`, `True`, `Red` with
  no explicit constructor call) always compiles to just the constant tag
  integer — there is no existing mechanism for a bare reference to also
  carry an accompanying value.

The consequence: a variant that carries a discriminant field **cannot** use
today's bare-int optimization — if `READ_MIN_OCCURANCES` compiled to a plain
`i32.const 0` tag, there'd be nowhere to also store the field value `0`
itself (and no way to tell "tag" from "field value" if they happened to
collide numerically for a different variant). So a discriminant enum's
variants must **always heap-allocate**, exactly like today's payload
variants — this feature reuses that existing scheme rather than inventing a
new one.

## Design

### Grammar

```js
enum: ($) =>
  seq(
    "enum",
    field("name", $.type_identifier),
    field("params", optional(seq("(", commaSep1($.enum_param), ")"))),
    "=",
    $._indent,
    optional(repeat(alias($.enum_field, $.field))),
    $._dedent,
  ),

enum_param: ($) =>
  seq(field("name", $.var_identifier), ":", field("type", $.type)),

enum_field: ($) =>
  seq(
    "|",
    field("name", $.type_identifier),
    field(
      "parameters",
      optional(choice(
        seq("[", commaSep1(choice($.type_identifier, $.generic)), "]"), // existing: generic type payload
        seq("(", commaSep1($.expression), ")"),                        // new: discriminant value literals
      )),
    ),
  ),
```

The bracket form (`[...]`, existing) and the paren form (`(...)`, new) are
distinguished by delimiter, matching the rest of the language's convention
post-migration: brackets for type-level content, parens for value-level
content — a discriminant value list is values, not types, so it naturally
takes parens, the same delimiter a constructor call already uses for its
arguments.

### AST

```rust
pub struct Enum {
    pub name: String,
    pub params: Vec<EnumParam>,   // new; empty for every enum declared without "(...)"
    pub variants: Vec<EnumVariant>,
}

pub struct EnumParam {           // new
    pub name: String,
    pub ty: Type,
}

pub struct EnumVariant {
    pub name: String,
    pub fields: Vec<String>,     // existing: generic/type payload names, unchanged meaning
    pub values: Vec<Expr>,       // new: discriminant literal values, empty for ordinary variants
}
```

A variant has either a non-empty `fields` (today's generic payload) or a
non-empty `values` (this feature), never both — enforced by the checker
(see below), not the grammar (the grammar can't tell a bare type name from a
literal expression apart at the same position without this kind of
cross-check, so it accepts either shape structurally and the checker
rejects the mixed case with a clear error).

### Checker

- **Declaration-time validation:** for an enum with non-empty `params`,
  every variant must supply exactly `params.len()` values, and each value's
  inferred type must unify with the corresponding param's declared type
  (e.g. the literal `0` against `Int`). A variant supplying the wrong count,
  or a value of the wrong type, is a checker error. An enum with EMPTY
  `params` must have every variant's `values` also empty (this is what "an
  enum is either a discriminant enum or an ordinary enum" means in
  practice) — a variant with non-empty `values` on a param-less enum is
  also a checker error (most likely to happen by a typo like accidentally
  writing `Some(5)` instead of `Some[Int]` for an ordinary generic enum;
  the error should say so plainly).
- **Field access (`self.n`, `obj.n`):** extend the existing field-access
  check (today: receiver type must resolve to a `Class` in `ClassEnv`) with
  a second lookup path: if the receiver's type resolves to an `Enum` name
  that has non-empty `params` (tracked in a new `EnumParams` map alongside
  the existing `EnumVariants`/`ClassEnv` context maps), resolve the field
  by name against that enum's declared params exactly as a class field
  would be resolved — same "field not found" error shape, just checked
  against `EnumParams` instead of `ClassEnv` when the name isn't a class.
  Field access on an enum with EMPTY params still falls through to today's
  behavior (class-only, or the permissive "unmodeled type" escape hatch)
  — unchanged.

### Codegen

- **Construction of a bare discriminant-variant reference**
  (`READ_MIN_OCCURANCES` used as a value, no explicit call): today this
  compiles `Expr::TypeName(n)` to a bare `I32Const(tag)` when the variant
  is payload-free. For a variant belonging to a discriminant enum (non-empty
  declared `values`), codegen instead reuses the EXISTING payload-variant
  construction path (`compile_variant_construction`) directly, using the
  variant's own declared literal `values` (compiled as constants) as the
  "field values" to store — structurally as if the user had written
  `READ_MIN_OCCURANCES(0)` explicitly at every use site, except the `0`
  comes from the variant's declaration, not the call site (there is no call
  site; syntactically it's still a bare reference). This means these
  variants always heap-allocate, matching the Current State constraint
  above — the bare-int optimization is simply not applied to them.
- **Field access codegen (`self.n`):** mirrors the existing class field-load
  codegen exactly (`I32Load`/`I64Load`/`F64Load` at `(field_idx + 1) * 8`
  from the heap pointer — `+1` because slot 0 is always the tag, matching
  today's payload-variant layout) — the only change is resolving
  `field_idx`/width from the enum's declared params (via the new
  `EnumParams` lookup) instead of `ClassEnv`, when the receiver's static
  type is a discriminant enum rather than a class.
- **Pattern matching** (`match` against a discriminant-enum value by variant
  name, e.g. `match step \n READ_MIN_OCCURANCES => ...`) is unaffected —
  since these variants are now always heap pointers (never bare ints), the
  existing payload-variant tag-load-and-compare path in match codegen
  applies uniformly, with no need for the "is this a small int or a
  pointer" branch discriminant enums currently force ordinary enums to
  have (every variant of a discriminant enum is a pointer, so that branch
  is simply never taken for this kind of enum).

### Testing strategy

- Tree-sitter corpus: a discriminant-enum declaration (`enum Step(n: Int) =
  | READ_MIN_OCCURANCES(0) | ...`), confirming the new `enum_param` and the
  paren-form `enum_field` parameters parse into the expected tree; confirm
  today's bracket-form (`| Some[T]`) and truly nullary (`| Red`) variants
  are unaffected.
- `plum-checker` tests: correct arity/type-checked discriminant values pass;
  wrong arity, wrong value type, and mixing discriminant values into a
  param-less enum's variant each produce a clear error; `self.n` field
  access on a discriminant-enum method type-checks and resolves to the
  right type; `self.n` on an ordinary enum (no declared params) still
  errors exactly as it does today.
- `plum-wasm-codegen` tests: a method that reads `self.n` off a
  discriminant-enum value returns the declared literal for each variant
  (covering at least two different variants, to prove the field is
  correctly positioned per-instance, not hardcoded to one variant's
  value); confirm a discriminant-enum value used in `match` (destructuring
  by variant name, not by field) still resolves and runs correctly,
  exercising the "always a pointer, never a bare int" codegen path noted
  above.