lab/sx
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(reify): name Phase 4 self-reference pair declare()/define()

Browse Source 
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.
This commit is contained in:
agra
2026-06-16 18:45:08 +03:00
parent ae5de1e687
commit 04e833a825
2 changed files with 27 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
current/PLAN-REIFY.md
View File

@@ -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 |