From a7dde2efd1045ca3bf3919911fd8f10bc142f4b9 Mon Sep 17 00:00:00 2001 From: agra Date: Tue, 16 Jun 2026 22:08:50 +0300 Subject: [PATCH] docs(metatype): declare(name) + self-reference done; update plan/checkpoint --- current/CHECKPOINT-METATYPE.md | 83 ++++++++++++++++++---------------- current/PLAN-METATYPE.md | 46 ++++++++++++------- 2 files changed, 72 insertions(+), 57 deletions(-) diff --git a/current/CHECKPOINT-METATYPE.md b/current/CHECKPOINT-METATYPE.md index 8f34b5c0..9d732086 100644 --- a/current/CHECKPOINT-METATYPE.md +++ b/current/CHECKPOINT-METATYPE.md @@ -4,31 +4,32 @@ Companion to [PLAN-METATYPE.md](PLAN-METATYPE.md). Update after every step (one step at a time, per the cadence rule). ## Last completed step -**The `declare`/`define` floor — the compiler's only type-construction surface.** -Two comptime `#builtin`s mint types; every constructor (`RecvResult`, `TryResult`, -the one-shot form) is plain sx built over them. The compiler has ZERO knowledge of -any named constructor. +**Self-reference — recursive enums via `declare("Name")` + `*Name`.** The +`declare`/`define` floor now supports self-referential types. -- `declare() -> Type` mints an empty (undefined) nominal slot; `define(handle, - info) -> Type` decodes the `TypeInfo` value (variant names + payload Type-tags), - names the slot from `EnumInfo.name`, completes it byte-identical to a source - enum, and returns the handle (so the one-shot form chains: - `T :: define(declare(), info)`). Interp executes both against a `mint` TypeTable - handle (`setMintTable`); `defineEnum` + `decodeVariantElements` in `interp.zig`. -- A `::` binding or type-fn body that calls a `Type`-returning fn is - **comptime-evaluated** (`evalComptimeType`), running the `declare`/`define` - builtins to mint the type — no constructor-name pattern-matching. `decl.zig` - trigger = `fnReturnsTypeValue`; type-fn trigger = `returnExprMintsType` - (return is a `define(…)` call or a bodied `-> Type` helper). -- Nominal identity rides the type-fn instantiation cache (`renameNominalType` - re-keys the minted type to the mangled name); `RecvResult(i64)` at two sites is - ONE type. -- The type NAME travels in `EnumInfo.name` — the compiler derives no name from a - binding LHS. +- `declare(name) -> Type` mints an empty (undefined) nominal slot NAMED `name`; + `define(handle, info) -> Type` decodes the `TypeInfo` value (variant names + + payload Type-tags), fills the slot byte-identical to a source enum, and returns + the handle (one-shot form chains: `T :: define(declare("T"), info)`). Interp + executes both against a `mint` TypeTable handle; `defineEnum` + + `decodeVariantElements` in `interp.zig`. +- **Self-reference:** `evalComptimeType`'s `preregisterForwardTypes` scans the + comptime expression (and a called ctor fn's body) for `declare("Name")` calls + and, before the body lowers, registers each as an empty forward nominal type AND + binds it as a type alias. The alias is essential — a `Name :: ctor()` decl makes + `Name` a const_decl author, so a `*Name` self-reference resolves through the + forward-ALIAS path (`type_aliases_by_source`), which a bare `findByName` + registration alone does NOT satisfy (it returns a pending empty-struct stub). The + interp's `declare` returns that same slot; `define` fills it. +- A `::` binding or type-fn body calling a `Type`-returning fn is + **comptime-evaluated** (`evalComptimeType`) — no constructor-name knowledge. + `decl.zig` trigger = `fnReturnsTypeValue`; type-fn trigger = `returnExprMintsType`. +- Nominal identity rides the type-fn instantiation cache (`renameNominalType`). +- The type NAME is on `declare(name)` (compile-time string), not `EnumInfo`. -Examples green on the floor: `0614` (one-shot `define(declare(), …)`), `0615` -(type-fn identity), `0617` (channel result types). `field_type` reflection still -green (`0616`). Full suite green (673 examples). +Examples green: `0614` (one-shot), `0615` (type-fn identity), `0617` (channel +results), **`0618` (recursive `*List`: construct, match through pointer, recursive +traversal)**; `field_type` reflection `0616`. Full suite green (674 examples). ## Current state - `modules/std/meta.sx`: `EnumVariant` / `EnumInfo{ name, variants }` / `TypeInfo` @@ -36,7 +37,8 @@ green (`0616`). Full suite green (673 examples). `RecvResult($T)` / `TryResult($T)` sx constructors over `define(declare(), …)`. - Compiler primitives only: `declare`/`define` (construction), `field_type` (reflection). No constructor-name knowledge anywhere in the compiler — every - named constructor is sx. + named constructor is sx. `declare(name)` carries the type name (compile-time + string) for forward-type registration. - `type_info` still bails loudly (`call.zig:tryLowerReflectionCall`) — pending. ## Decision (kept) @@ -45,31 +47,32 @@ in the always-loaded prelude interns them into every module's type table and shifts every `.ir` snapshot. On-demand import keeps the prelude clean. ## Next step -**Self-reference (recursive / mutually-recursive enums).** The two-statement form -`List :: declare(); define(List, .enum(.{ … payload = *List … }))`: `declare` -binds the handle, `define` completes it, and `*List` resolves because a pointer to -an undefined slot is legal. Needs the top-level `define(…)` statement form to run -at comptime in the window before any use of the type's layout (a bare top-level -call doesn't parse today — decide the surface). Pairs with a `make_enum(variants: -[]EnumVariant)` sx helper (a computed, non-literal variant list — exercises the -interpreter decoding a value-arg slice). - -Then: **`type_info($T) -> TypeInfo`** (reflect a type INTO a value — the inverse of -`define`'s decode; widen `TypeInfo` past `` `enum `` + construct a `[]EnumVariant` -value in the interp; its own focused effort) and **validation + loud diagnostics** -(dup variants, by-value self-ref, never-defined `declare`, use-before-define). +Pick any (independent): +- **`make_enum(variants: []EnumVariant)`** sx helper over a COMPUTED (non-literal) + variant list — exercises the interpreter decoding a value-arg slice in `define` + (vs. the literal `.[ … ]` the current examples use). +- **`type_info($T) -> TypeInfo`** — reflect a type INTO a value (inverse of + `define`'s decode); widen `TypeInfo` past `` `enum `` + construct a + `[]EnumVariant` value in the interp. Bails loudly today in + `call.zig:tryLowerReflectionCall`. Its own focused effort. +- **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. ## Known issues None. ## Log +- **Self-reference done.** `declare(name)` + `preregisterForwardTypes` (forward + type + alias before body lowers) → `*Name` resolves; recursive `*List` enum + constructs, matches through the pointer, and traverses recursively. `0618` locks + it. `declare` gained its `name` arg; `EnumInfo.name` dropped. Suite green (674). - **declare/define floor established.** The comptime type-construction surface is two primitives (`declare`/`define`); all named constructors are sx. A `::` binding or type-fn body that calls a `Type`-returning fn is comptime-evaluated (the builtins mint the type) — no syntactic constructor recognition in the compiler. - Name travels in `TypeInfo`. Examples 0614 (one-shot) / 0615 (type-fn identity) / - 0617 (channel results) run on the floor; `field_type` reflection (0616) unchanged. - Full suite green (673). + Examples 0614 (one-shot) / 0615 (type-fn identity) / 0617 (channel results) on the + floor; `field_type` reflection (0616) unchanged. - **Stream carved (earlier).** Selected as the first async-first foundation: gates channel result types (`RecvResult($T)`) and `race`'s synthesized union, fully validated, self-contained, testable in isolation (`06xx` comptime). diff --git a/current/PLAN-METATYPE.md b/current/PLAN-METATYPE.md index 368287cb..d0b348f1 100644 --- a/current/PLAN-METATYPE.md +++ b/current/PLAN-METATYPE.md @@ -4,10 +4,11 @@ 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. +- **`declare(name) -> Type`** — mint a NEW empty (undefined) nominal type NAMED + `name`, returned as a first-class `Type` handle. The compiler registers the + forward type at compile time, so the body can reference it (`*Name`). - **`define(handle, info) -> Type`** — fill a declared handle's body from a - `TypeInfo` *value* (which carries the type's name), and return the handle. + `TypeInfo` *value*, and return the handle (so the one-shot form chains). - **`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 @@ -19,17 +20,20 @@ compiler surface. Every higher-level constructor is **plain sx built over ```sx // one-shot (non-recursive): declare + define chained, define returns the handle -T :: define(declare(), .enum(.{ name = "T", variants = .[ … ] })); +T :: define(declare("T"), .enum(.{ 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 } ] })); +// recursive: a ctor fn names the forward type via declare, references it as *Name +List :: make_list(); +make_list :: () -> Type { + h := declare("List"); + return define(h, .enum(.{ variants = .[ + EnumVariant.{ name = "cons", payload = *List }, // self-reference + 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 = .[ + return define(declare("RecvResult"), .enum(.{ variants = .[ EnumVariant.{ name = "value", payload = T }, EnumVariant.{ name = "closed", payload = void } ] })); } @@ -52,8 +56,13 @@ tagged-union (design [../design/execution-evolution-roadmap.md](../design/execut `-> 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. +3. **Name on `declare`.** `declare("Name")` carries the name as a compile-time + string so `preregisterForwardTypes` (in `evalComptimeType`) can register the + forward type — and bind it as a type alias — BEFORE the body lowers. That's + what makes a `*Name` self-reference resolve (a `Name :: ctor()` decl makes + `Name` a const_decl author, so `*Name` resolves through the forward-ALIAS path; + the alias binding, not just the table registration, is what satisfies it). The + interp's `declare` returns the same slot by name; `define` fills it in place. 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). @@ -92,11 +101,14 @@ while red. Examples: `06xx` (comptime), `11xx` (diagnostics). - [x] `field_type` reflection (`examples/0616`). - [x] 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). +- [x] **Self-reference** — recursive enums via `declare("Name")` + `*Name` in a + constructor fn (`preregisterForwardTypes` registers the forward type + alias + before the body lowers). `examples/0618` (recursive `*List`: construct, match + through the pointer, recursive traversal). Mutual recursion / by-value-self-ref + rejection fall out of the same mechanism (F5 adds the loud by-value check). +- [ ] **`make_enum(variants: []EnumVariant)`** sx helper over a COMPUTED + (non-literal) variant list — exercises the interpreter decoding a value-arg + slice in `define`. - [ ] **`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