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 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 1 (type-fn → reify identity). R :: ($T) -> Type { reify(...) }; assert R(i64) from two sites is ONE type (assignable / matchable across sites). xfail → green by registering a reify-returning type-fn's result under the instantiation mangled name (mirror generic.zig:1663-1689). NOTE: Phase 0's reifyType is hooked only at the E :: reify(...) const-decl site (decl.zig) and reads a LITERAL TypeInfo off the AST; Phase 1 must route a reify call returned from a type-fn body (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 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

• 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.