From 04e833a825513867f4a03db1e453c41c496b4628 Mon Sep 17 00:00:00 2001 From: agra Date: Tue, 16 Jun 2026 18:45:08 +0300 Subject: [PATCH] docs(reify): name Phase 4 self-reference pair declare()/define() User picked the declaration-vs-definition split over reserve/complete. declare() returns a forward nominal Type handle (named from the :: LHS); define(handle, info) fills its body. reify(info) stays the one-shot sugar. Updated PLAN-REIFY Phase 4 + Contract 5 + CHECKPOINT-REIFY. --- current/CHECKPOINT-REIFY.md | 21 +++++++++++---------- current/PLAN-REIFY.md | 31 ++++++++++++++++--------------- 2 files changed, 27 insertions(+), 25 deletions(-) diff --git a/current/CHECKPOINT-REIFY.md b/current/CHECKPOINT-REIFY.md index cd3d34b3..62b360d4 100644 --- a/current/CHECKPOINT-REIFY.md +++ b/current/CHECKPOINT-REIFY.md @@ -61,16 +61,17 @@ only at the `E :: reify(...)` const-decl site (`decl.zig`) and reads a LITERAL (and likely generalize the literal-AST reader, or evaluate via the interpreter, for non-literal `TypeInfo`). -SELF-REFERENCE = Phase 4, API DECIDED (user-directed): explicit **`reserve()` → -`complete()`** (NOT a `reify_rec((self)=>…)` closure). `reserve()` returns a forward -nominal `Type` handle (named from the `::` LHS) usable freely in any later `TypeInfo` -— `*List`, `[]List`, and across types for MUTUAL recursion the one-`self` closure -couldn't express; `complete(handle, info)` fills the body. `reify(info)` stays as the -one-shot sugar. Maps onto existing machinery: reserve = empty nominal slot -(`reserveShadowEnumSlot`-style), complete = `buildEnumInfo` + `updatePreservingKey`, -struct-stub→tagged_union re-key already handled (`internNamedTypeDecl`'s -`adoptsForwardStructStub`). Loud invariants: never-completed reserve = hard error; -by-value self-inclusion rejected (infinite size). Full write-up in PLAN-REIFY Phase 4. +SELF-REFERENCE = Phase 4, API DECIDED (user-directed): explicit **`declare()` → +`define(h, info)`** (the declaration-vs-definition split; NOT a `reify_rec((self)=>…)` +closure). `declare()` returns a forward nominal `Type` handle (named from the `::` +LHS) usable freely in any later `TypeInfo` — `*List`, `[]List`, and across types for +MUTUAL recursion the one-`self` closure couldn't express; `define(handle, info)` fills +the body. `reify(info)` stays as the one-shot sugar. Maps onto existing machinery: +declare = empty nominal slot (`reserveShadowEnumSlot`-style), define = `buildEnumInfo` ++ `updatePreservingKey`, struct-stub→tagged_union re-key already handled +(`internNamedTypeDecl`'s `adoptsForwardStructStub`). Loud invariants: never-defined +declare = hard error; by-value self-inclusion rejected (infinite size). Full write-up +in PLAN-REIFY Phase 4. ## Known issues None yet. diff --git a/current/PLAN-REIFY.md b/current/PLAN-REIFY.md index 02b6a4e3..277dc663 100644 --- a/current/PLAN-REIFY.md +++ b/current/PLAN-REIFY.md @@ -25,9 +25,9 @@ tagged-union, and **replaces** a would-be `enum($T)` generic-enum language featu 3. **Validate loudly** at the `intern`/`internNominal` choke point (`types.zig:411-439`). 4. **Comptime-only, JIT-free** — a type-table op in the interpreter; no S1 dependency. 5. **Reference-based self-reference** (`*Self`/`[]Self`) via an explicit - **`reserve()` → `complete()`** pair (reserve-placeholder→complete reuse of + **`declare()` → `define()`** pair (reserve-placeholder→complete reuse of `nominal.zig:86/108/120`, `types.zig:442`); **by-value recursion rejected**. (See - Phase 4 — the `reserve`/`complete` API supersedes the earlier `reify_rec` closure.) + Phase 4 — the `declare`/`define` API supersedes the earlier `reify_rec` closure.) Surface follows the **`#builtin`** pattern of the existing reflection builtins (`type_of`/`field_count`/`field_name` in `library/modules/std/core.sx`, @@ -81,28 +81,29 @@ Examples: `06xx` (comptime, deterministic), `11xx` (diagnostics for loud failure |---|---|---|---| | 3.0 | lock | `make_enum(variants) -> Type` (sx lib over `reify`); `RecvResult($T)`/`TryResult($T)` as type-fns. Behavior-lock: `RecvResult(i64)` constructs + matches. | `library/modules/std/*` | -### Phase 4 — reference-based self-reference (explicit reserve → complete) -> **API decision (user-directed):** an explicit **`reserve()` / `complete()`** pair, -> NOT a `reify_rec((self) => …)` closure. `reserve()` returns a forward-declared -> nominal `Type` HANDLE — a real `Type` value usable freely in any later `TypeInfo` -> (`*List`, `[]List`, and across types for MUTUAL recursion, which the one-`self` -> closure can't express). `complete(handle, info)` fills the body. `reify(info)` stays -> as the one-shot sugar (= reserve + complete + return) for the non-recursive case. -> No special self-ref node in `TypeInfo` — a reserved type is just a `Type`. +### Phase 4 — reference-based self-reference (explicit declare → define) +> **API decision (user-directed):** an explicit **`declare()` / `define(h, info)`** +> pair (the canonical declaration-vs-definition split), NOT a `reify_rec((self) => …)` +> closure. `declare()` returns a forward-declared nominal `Type` HANDLE — a real +> `Type` value usable freely in any later `TypeInfo` (`*List`, `[]List`, and across +> types for MUTUAL recursion, which a one-`self` closure can't express). +> `define(handle, info)` fills the body. `reify(info)` stays as the one-shot sugar +> (= declare + define + return) for the non-recursive case. No special self-ref node +> in `TypeInfo` — a declared type is just a `Type`. > ```sx -> List :: reserve(); // name from the `::` LHS -> complete(List, .enum(.{ variants = .[ +> List :: declare(); // name from the `::` LHS +> define(List, .enum(.{ variants = .[ > EnumVariant.{ name = "cons", payload = *List }, // reference it freely > EnumVariant.{ name = "nil", payload = void } ] })); > ``` -> Loud invariants: (a) a `reserve()` never `complete()`d = hard error at end of +> Loud invariants: (a) a `declare()` never `define()`d = hard error at end of > comptime (no silent empty type); (b) by-VALUE self-inclusion (`payload = List`, not > `*List`) rejected — infinite size, same check recursive source types get. | Step | Commit | What | Files | |---|---|---|---| -| 4.0 | xfail | `reserve()` returns a forward nominal `Type`; `complete()` fills it. Recursive enum via `*Self` (tree/list). Red. | `examples/06xx-*` | -| 4.1 | green | `reserve` = intern empty nominal slot (`reserveShadowEnumSlot`-style); `complete` = `buildEnumInfo` + `updatePreservingKey`; struct-stub→tagged_union re-key already handled by `internNamedTypeDecl` (`adoptsForwardStructStub`). | `src/ir/lower/nominal.zig`, `src/ir/lower/decl.zig`, `src/ir/types.zig` | +| 4.0 | xfail | `declare()` returns a forward nominal `Type`; `define()` fills it. Recursive enum via `*Self` (tree/list). Red. | `examples/06xx-*` | +| 4.1 | green | `declare` = intern empty nominal slot (`reserveShadowEnumSlot`-style); `define` = `buildEnumInfo` + `updatePreservingKey`; struct-stub→tagged_union re-key already handled by `internNamedTypeDecl` (`adoptsForwardStructStub`). | `src/ir/lower/nominal.zig`, `src/ir/lower/decl.zig`, `src/ir/types.zig` | ### Phase 5 — validation + loud diagnostics | Step | Commit | What | Files |