sx/current/CHECKPOINT-REIFY.md

CHECKPOINT-REIFY — comptime type_info / reify (async-first foundation, step 3)

Companion to PLAN-REIFY.md. Update after every step (one step at a time, per the cadence rule).

Last completed step

Phase 2.1 (green) — field_type done. field_type($T, i) -> Type is implemented over the type table (fieldTypeOf in lower/generic.zig, re-exported on Lowering): struct field / tagged-union + union variant payload (.void for a tagless variant) / tuple element / array + vector element; OOB and memberless types poison to .unresolved with a loud diagnostic (never a silent default). It folds at lower time, so it composes inside type_eq / type_name / any type-arg slot. examples/0616 green (struct fields name+type, type_eq fold, tagged-union payloads incl. quit → void). Full suite green (672 examples, 447 unit). Cadence: 2.0 xfail (empty marker, RED) → 2.1 green (this commit).

type_info is NOT done — it still bails loudly in call.zig:tryLowerReflectionCall. It builds a full TypeInfo value (inverse of reify) and is the larger Phase 2.2 step (see Next step).

(prior) Phase 1 (type-fn → reify identity) — COMPLETE. A type-fn body that returns

reify(...) now mints the enum under the instantiation's name: instantiateTypeFunction (lower/generic.zig) detects a reify-returning body (findReturnReifyCall) and routes it to reifyType(<mangled-or-alias name>, reify_call) with the type-arg bindings active (so payload = T resolves to the bound arg) — placed BEFORE the general case, which would otherwise route the reify call to the inline-position loud bail. Registering under the mangled name lets the fn's top-of-instantiation cache return the SAME TypeId on the second instantiation → Box(i64) at two independent sites is ONE type (Contract 1). examples/0615 green (build()→consume() cross-site, plus b : Box(i64) = .none); full suite green (671 examples, 447 unit). Cadence: 1.0 xfail (empty marker, RED) → 1.1 green (this commit).

(prior) Phase 0.2 (green) — Phase 0 COMPLETE. Implemented reify(.enum(...)):

Lowering.reifyType (in lower/nominal.zig) reads the flat-enum TypeInfo literal off the AST, synthesizes an ast.EnumDecl, and feeds it through the SAME type_bridge.buildEnumInfo path source enums use → the minted type is byte-identical to a hand-written enum { value: i64; closed; } and flows through enum codegen unmodified (Contract 2 confirmed — a source enum exhibits the exact same construct/match behavior, verified by probe). Wired at the E :: reify(...) const-decl hook in lower/decl.zig. examples/0614 green (value 3 / closed, exit 0); snapshots captured; full suite green (670 examples, 447 unit). Unsupported reify shapes bail loudly via reifyBail (never a silent default).

Also landed (user-directed, separate commit feat(parser):): reserved keyword as a member name after . (.enum, case .enum:, x.enum) — so the reify example reads reify(.enum(...)) without a backtick. readme updated.

Two earlier Phase-0 commits

• 0.1 (xfail). Added examples/0614 + empty .exit marker → RED.
• 0.0 (lock). Added the comptime type-metaprogramming surface as the on-demand module library/modules/std/meta.sx (NOT the prelude — see decision below): EnumVariant/EnumInfo/TypeInfo data types + bodyless #builtin decls reify / type_info / field_type. Each builtin bails LOUDLY when reached unimplemented (no silent default). Unit test src/parser.test.zig (registered in src/root.zig) locks that the decls parse. zig build test green (447/447 unit, 669/669 examples).

Current state

• modules/std/meta.sx declares the surface; the variant uses the backtick raw escape `enum (reads as the keyword, not a mangled enum_).
• Loud bails wired (unimplemented → diagnostic, never a silent type):
  • reify(...) in a :: type-alias position → decl.zig (the .call const-decl branch) emits "reify is not yet implemented (REIFY Phase 0.2)" and poisons the alias to .unresolved. This is also where Phase 0.2 will hook the real construction.
  • reify / field_type in any other type position → generic.zig:resolveTypeCallWithBindings (defense-in-depth).
  • type_info(...) in expression position → call.zig:tryLowerReflectionCall.
• No interpreter-side construction yet — reify mints nothing.

Decision (0.0)

Meta lives in modules/std/meta.sx, not the prelude (core.sx). Declaring the data types in the always-loaded prelude interns them into every module's type table and shifts every .ir snapshot (broke 37 examples in a trial). An on-demand import keeps the prelude clean; reify users #import "modules/std/meta.sx". (User-directed.)

Next step

Phase 2.2 (type_info($T) -> TypeInfo). Reflect a type into a TypeInfo value — the inverse of reify. Two sub-pieces, both non-trivial: (a) widen the meta.sx TypeInfo data model beyond `enum (struct / tuple variants); (b) build the value at comptime — a []EnumVariant-style slice of structs holding strings (name) + Type tags (payload), populated from the type table. This is comptime value-CONSTRUCTION (allocating slice/struct/string/type-tag values in the interpreter), materially larger than 2.1's fold-to-a-TypeId. Currently bails loudly in call.zig:tryLowerReflectionCall. Best done as its own session for context room.

NOTE (round-tripping): reifyType still reads a LITERAL TypeInfo off the AST (fine for the inline-literal + type-fn-over-literal cases of Phases 0–1). Once 2.2 produces a COMPUTED TypeInfo, feeding it back into reify needs the reader generalized (or interp evaluation of the TypeInfo value) — handle that when 2.2 enables round-tripping.

Alternatively jump to Phase 3 (make_enum + RecvResult/TryResult sx lib over reify) — that only needs reify (have it) + type-fns (have them), not type_info.

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.

Log

• 2.1 (green) — field_type done. fieldTypeOf over the type table (struct/tagged-union/union/tuple/array/vector; OOB+memberless = loud poison); folds at lower time, composes in type_eq/type_name; 0616 green. type_info still pending (Phase 2.2 — builds a TypeInfo value).
• 2.0 (xfail). 0616 + empty .exit marker → RED (field_type bailed).
• 1.1 (green) — Phase 1 done. Type-fn body return reify(...) routes through reifyType under the instantiation name (findReturnReifyCall + mangled-name registration); Box(i64) at two sites = one type (Contract 1); 0615 green.
• 1.0 (xfail). 0615 + empty .exit marker → RED (reify bailed in type-fn body).
• 0.2 (green) — Phase 0 done. reifyType mints a flat enum from a literal TypeInfo via the shared buildEnumInfo path; 0614 green; Contract 2 confirmed (reify'd enum == source enum, same construct/match). Payload-less variant idiom in the example is c : E = .closed; (enum-literal target), same as a source enum.
• parser (user-directed). Keyword as member name after . — see feat(parser).
• 0.1 (xfail). 0614 + empty .exit marker → RED.
• 0.0 (lock). Meta surface in modules/std/meta.sx (data types + 3 bodyless #builtin decls), loud bails at all three reach points, src/parser.test.zig parse-lock. Two user-directed refinements folded in: variant uses `enum raw escape; surface moved out of the prelude into its own module to avoid type-table / .ir-snapshot churn. zig build test green.
• Stream carved. Selected as the first async-first foundation: reify gates both channel result types (RecvResult($T)) and race's synthesized union, is fully validated (3 reviewers), and is a self-contained compiler/type-system feature testable in isolation (06xx comptime). Generic-enum syntax dropped in its favor.