sx/current/PLAN-METATYPE.md

PLAN-METATYPE — comptime type metaprogramming (declare / define + reflection)

Goal

Comptime type metaprogramming with the smallest possible compiler surface:

• declare() -> Type — mint a NEW empty (undefined) nominal type, returned as a first-class Type handle.
• define(handle, info) -> Type — fill a declared handle's body from a TypeInfo value (which carries the type's name), and return the handle.
• type_info($T) -> TypeInfo — reflect a type INTO data (the inverse of define's decode). Pending.
• field_type($T, i) -> Type — the i-th field / variant-payload / element type of $T. Done.

These four #builtins in library/modules/std/meta.sx are the entire compiler surface. Every higher-level constructor is plain sx built over declare/define — the compiler knows none of them by name:

// one-shot (non-recursive): declare + define chained, define returns the handle
T :: define(declare(), .enum(.{ name = "T", variants = .[ … ] }));

// recursive / mutually-recursive: keep the handle, reference it in its own body
List :: declare();
define(List, .enum(.{ name = "List", variants = .[
    EnumVariant.{ name = "cons", payload = *List },
    EnumVariant.{ name = "nil",  payload = void } ] }));

// type-fns are ordinary sx (channel result types, etc.)
RecvResult :: ($T: Type) -> Type {
    return define(declare(), .enum(.{ name = "RecvResult", variants = .[
        EnumVariant.{ name = "value",  payload = T    },
        EnumVariant.{ name = "closed", payload = void } ] }));
}

This gates channel result types (RecvResult($T)) and race's synthesized tagged-union (design ../design/execution-evolution-roadmap.md §7 step 3), and replaces a would-be enum($T) language feature.

How it works (the locked design)

1. Two comptime interp builtins. declare mints an empty tagged_union slot in the type table; define decodes the TypeInfo value (variant-name strings + payload Type-tags) and completes the slot byte-identical to a source enum's buildEnumInfo output, so it flows through enum codegen unmodified. The interp mutates the type table via a mint handle the host sets (setMintTable).
2. No syntactic constructor recognition. A :: binding or type-fn body that calls a Type-returning fn is comptime-evaluated (evalComptimeType): the expression runs through the interpreter, the declare/define builtins mint the type, and the result type_tag is bound. decl.zig triggers on a non-generic -> Type fn call; instantiateTypeFunction triggers on a type-fn body that returns a define(…) call (or a bodied -> Type helper) — see generic.zig:returnExprMintsType.
3. Name travels in the data. define names the slot from EnumInfo.name; the compiler derives no name from a binding LHS. type_info round-trips it.
4. Nominal identity rides the existing type-fn mangled-name instantiation cache: RecvResult(i64) at two sites memoizes to ONE TypeId (the body runs once; renameNominalType re-keys the minted type to the mangled name).
5. Comptime-only, JIT-free. declare/define are interp ops; reaching them at runtime / emit is a hard error.
6. Undefined-until-defined. declare() mints an undefined slot; using it (construct / match / size) before its define is a loud diagnostic. A pointer to an undefined slot (*Self) is fine — that's what self-reference needs.

Key code anchors

• Builtins: BuiltinId.declare / .define (src/ir/inst.zig); lowering to callBuiltin (src/ir/lower/call.zig:tryLowerReflectionCall); interp exec + defineEnum + decodeVariantElements (src/ir/interp.zig); mint field + setMintTable.
• Comptime evaluation: evalComptimeType / renameNominalType (src/ir/lower/comptime.zig); decl trigger fnReturnsTypeValue (src/ir/lower/decl.zig); type-fn trigger returnExprMintsType + instantiateTypeFunction (src/ir/lower/generic.zig).
• Reflection: field_type → fieldTypeOf (src/ir/lower/generic.zig).
• Surface: library/modules/std/meta.sx (on-demand import — NOT the prelude, to avoid shifting every .ir snapshot).

Cadence (IMPASSIBLE)

No commit may both add a test AND make it pass (xfail-then-green, or a behavior lock). zig build && zig build test after every step. Never regenerate snapshots while red. Examples: 06xx (comptime), 11xx (diagnostics).

Status

• declare / define comptime builtins + the mint plumbing.
• Comptime evaluation of a Type-returning :: RHS and type-fn body (the only triggers; no constructor-name knowledge in the compiler).
• Name-in-TypeInfo; nominal identity via the instantiation cache.
• field_type reflection (examples/0616).
• Examples green on the floor: 0614 (one-shot), 0615 (type-fn identity), 0617 (channel result types).
• Self-reference — the top-level List :: declare(); define(List, …) two-statement form with a *Self payload (recursive / mutually-recursive enums). Needs the define(…) top-level statement form to run at comptime in the right window. Pairs with a make_enum(variants: []EnumVariant) sx helper (computed variant list).
• type_info($T) -> TypeInfo — reflect a type INTO a value (inverse of define's decode): widen TypeInfo past `enum (struct/tuple) AND construct a []EnumVariant-style value in the interpreter. Bails loudly today in call.zig:tryLowerReflectionCall. Round-trips through define once it lands.
• Validation + loud diagnostics — duplicate variant names, by-VALUE self-reference (payload = List not *List → infinite size), a declare() never define()d (hard error), use-before-define. Emit at the intern/internNominal choke point; never a broken type.

Risks / watch

• Self-ref timing — define for the two-statement form must complete before any code uses the type's layout; a use-before-define must be a loud diagnostic, not a silent empty enum.
• Keep declare/define comptime-only: reaching them at runtime is a hard error (emit should bail loudly if one ever leaks into codegen).