Quartz Language Roadmap

Version: v5.26.0-alpha → Target: v6.0.0 (Production 3.0) Status: Self-Hosted Primary | Tests: QSpec 364/368 files (4 pre-existing: struct_destructure SIGSEGV, argparse_spec API, unqualified_patterns SIGSEGV, separate_compilation llc ×2) | 5,307 active tests, 137 pending | Stress: 401 pass, 0 pending | Fuzz: grammar-guided generator + 4-level oracle

Goal: Build a language that is airtight. Every feature complete, every edge case tested, every corner of the type system proven correct under adversarial pressure. Platform and ecosystem come later — get the language right first.

Current Focus: All P2.5 Language Features COMPLETE. All P0/P1/P2 phases complete. All 8 language features done (or-patterns, pattern binding, range step, named args, generators, spread, impl Trait returns, multi-clause def). Critical fixes done (vec_get OOB, Unicode, H-M completion). C backend complete (+ multi-word @value struct runtime fix). Debugger complete (DX.1 Phases 1-5.2). Cross-platform stdlib complete (FIX.5). WASM target complete (TGT.1). Remaining: spec hardening, final proof pass.

Latest (Mar 10, 2026): G.4 Cast Elimination Round 3 — ResolverEntry + MirDropEntry typed structs (310→253, 57 more casts eliminated). Three quick wins: (1) ResolverEntry struct in compiler_types.qz replaces [ast_store, node_id, as_int(name), tag] array literals — field access replaces indexed access + as_string() across 8 files (resolver, mir, mir_lower, codegen, codegen_c, liveness, quartz). (2) MirDropEntry struct replaces [var_name, type_name, depth] arrays in mir.qz — eliminates droppable stack casts. (3) Borrow source write-side as_int() removal in typecheck_walk.qz (3 sites). 2-stage bootstrap + fixpoint verified. Prior: DX.1 Phase 5.2 Enum DWARF. Prior: G.4 Round 2 (302→224). Prior: DOC.1 QUARTZ_REFERENCE.md Audit. Prior: LFA A.7 Bool Hygiene. Prior: TEST.2 Specification as Proof. Prior: TGT.1 WASM Target. Prior: FIX.6b Vec Multi-Word Runtime. Prior: FIX.5 Cross-Platform Stdlib. Prior: DX.1 Debugger (Phases 1-5.1). Prior: P.5.TC Typecheck Performance.

Known Bugs: ~~MIR drop-at-scope-exit not emitted~~ (FIXED). ~~Duplicate type detection false positives~~ (FIXED). ~~Build cache null pointer~~ (FIXED — X.7). ~~C bootstrap references in build system~~ (FIXED — FP). ~~Duplicate struct/enum not detected~~ (FIXED — Phase 0 string eq + or-operator). ~~stress_large_program_spec.qz SIGSEGV~~ (FIXED — heredoc interpolation + trait body + const-by-default). ~~If-expression type inference returns Void~~ (FIXED — NODE_IF tc_expr uses branch types, NODE_BLOCK double-evaluation eliminated). ~~Recursive str_eq in monomorphized generic context causes compiler hang~~ (FIXED — pointer-vs-content string comparison in mir_has_pending_spec and visited set). ~~String == is pointer comparison~~ (FIXED — X.8, mir_is_string_expr extended, 35 adversarial tests). ~~P.5 fixpoint blocked~~ (FIXED — Vec<String> substring false positive removed from string var detection, bootstrap IR surgery). ~~Heredoc \# escape not handled~~ (FIXED — lexer heredoc scanner now skips backslash-escaped chars). clang -O2 -x ir miscompiles self-hosted compiler IR (SIGSEGV on self-compile — use llc -O2 instead). ~~Regular "..." strings with literal embedded newlines hang the parser~~ (RESOLVED — was SIGSEGV manifestation, not parser bug; triple-quoted strings work correctly). ~~Subprocess QSpec tests SIGSEGV on some files~~ (FIXED — recursive mir_collect_captures_walk exhausted 8MB stack on closure-heavy files; replaced with iterative worklist walker). ~~Tier 2 incremental produces stale output~~ (FIXED — MIR constant-folds function bodies across modules; depgraph_invalidate_with_cutoff now always propagates from seed modules to direct dependents). ~~Template macro #{} in subprocess source lexed as interpolation~~ (FIXED — changed template macro syntax from #{} to ${} which avoids the string interpolation conflict). ~~default keyword clash prevents use as identifier~~ (FIXED — default is now a contextual keyword). ~~Variadic macro unquote_each hangs in subprocess~~ (FIXED — implemented parser + expander from scratch, was never implemented). ~~Drop infinite recursion in generated Type$drop functions~~ (FIXED — FIX.4, self param pushed onto droppable stack → recursive Type$drop(self) call; added str_ends_with(name, "$drop") guard at 2 sites in mir_lower.qz). ~~E-graph CSE produces invalid LLVM SSA references~~ (FIXED — FIX.4, eg_scoped_lookup used hashmap_get (returns Option<Int> pointer) as raw dest_id → __hashmap_get_raw). ~~QSpec subprocess tests flaky in full suite~~ (FIXED — FIX.4, /tmp/_qspec_sub_* temp files from previous tests interfering; added cleanup between test runs in Quakefile.qz). ~~Implicit-return struct literals parsed as struct destructuring~~ (FIXED — FIX.5b, Name { field: val } as last expression in block def triggers destructuring path instead of struct init; ps_error() doesn’t advance → infinite loop; fixed by adding return to all affected sites). ~~@cfg on extern "C" def hangs parser~~ (FIXED — FIX.5b, ps_skip_cfg_definition and ps_parse_decl attribute block missing TOK_EXTERN). ~~vec_pop returns zeroed struct fields for @value types~~ (FIXED — FIX.6b: root cause was ALL runtime vec functions (C + LLVM) using single-word i64 access instead of multi-word memcpy/memcmp with h[3] elem_width. 13 C runtime + 4 LLVM runtime functions fixed. 7 new tests). Multi-argument extern "C" declarations crash in multi-module compilation — “index out of bounds: index 1, size 1” in cg_emit_intrinsic. Zero-argument extern “C” works fine. Workaround: use 0-arg externs or add functions to C runtime as intrinsics. Discovered via P.5 timing (Mar 8, 2026).

Principles

We accept only world-class solutions.

Test-Driven Development: Write tests first. Implementation follows specification.
Fixpoint Validation: After ANY change to bootstrap or self-hosted, run ./self-hosted/bin/quake fixpoint.
No Shortcuts: If a feature can’t be done right, it waits. Technical debt compounds.
Document Changes: Update docs/QUARTZ_REFERENCE.md immediately after language changes.
Incremental Progress: Commit working states. Never leave the compiler broken.

# The sacred workflow
./self-hosted/bin/quake qspec     # All tests pass
./self-hosted/bin/quake fixpoint  # Fixpoint verified
git add -A && git commit          # Progress preserved

Priority Stack — Language Hardening First

The language must be airtight before we build anything around it. Every syntax change invalidates downstream tooling. Get the language right, then build the platform.

P0: Language Completeness & Correctness

Finish every language feature. Close every gap. No half-implemented semantics.

Rank	Phase	Gap Addressed	Current State
1	U.9 — Intersection Type Completion	~~”Core complete, edge cases deferred”~~ COMPLETE	14/14 core sub-phases done — canonical ordering, impossible detection, tc_type_meet, display names, mixed record+trait, return position, conflict detection fix, multi-trait bounds, 17 active tests. 3 items permanently deferred by design: type narrowing (incompatible with existential model), distributivity (unsound with effects), vtable dispatch (future `dyn Trait` phase). ~~Compiler hang~~ resolved (F.2 fix)
2	S2.5 — Safety Audit Holes	”12 7 1 0 remaining holes”	COMPLETE — ALL 12/12 holes fixed: #6 NODE_ASSIGN re-init (CRITICAL→DONE), #7 struct init move (MEDIUM→DONE), #13 lambda capture move (MEDIUM→DONE), #3 try/catch branch moves (MEDIUM→DONE), #9 enum payload move (LOW→DONE), #4 while error recovery (LOW→DONE), #8 return expr move (LOW→DONE), #10 match subject move (LOW→DONE, 3 tests), #11 NLL+move (LOW→DONE), #12 interprocedural borrow (LOW→DONE), #5 list comp move tracking (LOW→DONE, already implemented in typecheck_walk.qz, confirmed with 2 tests). #14 spawn (covered by #13), #15 defer (already correct). 18 tests across s25 spec files
3	F.2 — Generic Type Gaps	~~”HashMap threading, generic struct methods, multi-param generics”~~	COMPLETE — all 6 gaps fixed + Vec<Struct> ptype collision fix (struct registry index as arg2 prevents different struct Vec types collapsing to same ptype) + struct name propagation through vec_get/vec_pop/index. monomorphization loop guard, nested generic `>>` tokenization, field access type_args, multi-param dispatch, HashMap threading (already worked), typed global var declarations. 25 QSpec tests (14 original + 11 vec_struct_generics), fixpoint verified
4	F.4 — Concurrency Gaps	~~”Task extraction, cooperative cancellation, multi-level closure capture”~~	COMPLETE (3/3): Task extraction (ptype + await unwrap + codegen), multi-level closure capture (mir_ctx_bind_var), cooperative cancellation (`cancel_token_free` added, 18 tests in cancel_token_spec.qz covering token lifecycle, check-and-bail, task_group integration, cross-thread sharing, defer cleanup, edge cases). Deferred: hierarchical tokens, timeout tokens, `is_cancelled()` without task_group MIR flag fix
5	F.1 — Parser Completion	~~”`#{}` in closures causes OOM, `\|` disambiguation”~~	COMPLETE — investigated both issues: `#{}` in closures already works (Sprint 4 confirmed), `
6	CMF — Cross-Module Remaining	~~”dep_graph chained field access, str_split trailing empty”~~	COMPLETE — 5/5 P.2 bugs fixed. str_split trailing empty fixed: replaced strtok with strstr-based loop in qz_str_split_impl. 4 new edge-case tests

P1: Stress Test & Adversarial Hardening

Beat the shit out of it. Prove it’s solid or find what’s broken.

Rank	Phase	Gap Addressed	Current State
7	STRESS — Adversarial Test Suite	”~~190+ adversarial tests, bugs found and fixed~~”	COMPLETE — 16 stress files, 401 active tests, 0 pending. All 16 STRESS-PENDING items resolved. Fuzz testing infrastructure: grammar-guided program generator (`std/fuzz/gen.qz`) with depth-controlled random productions + 4-level oracle system (`std/fuzz/oracle.qz`: crash detection, determinism, IR validation via `opt -passes=verify`, differential testing). Delta debugging minimizer (`fuzz_shrink`). CLI tool (`tools/fuzz.qz`). Quake integration: `quake fuzz` (100 programs), `quake fuzz_long` (1000 programs, depth 12, crash saving), `quake fuzz_differential`. 13 QSpec tests in `fuzz_spec.qz`. it_pending triage: 9 network tests resolved (4→response parsing tests, 5→deferred), 2 arena tests activated (raw `arena_alloc` tracking wired), 1 TLS hostname deferred (FFI binding added), 6 permanent (existential type model, POSIX ERE, lli limitations).
8	SPEC.3-5 — Formal Specification	~~”SPEC.3+4 done, SPEC.5 remaining”~~	SPEC.3+4+5 COMPLETE: Eval semantics + memory model specs done. SPEC.5 Conformance Tests: 108 tests (85 eval + 23 memory) in conformance_eval_spec.qz + conformance_memory_spec.qz. All passing.
9	B — Benchmark Integrity	~~”Benchmark fairness, struct-heavy workloads”~~	HARDENED — 12 benchmark pairs (Quartz vs C). Fair C hash_map (dynamic resize at 75% load, backward-shift deletion), new C json_parse, linked_list memory leak fixed. struct_heavy benchmark added (Point3D + BoundingBox, 100K points × 50 iterations). Quake `bench_compile` task. Peak RSS measurement via `/usr/bin/time -l`. BENCHMARKS.md v2.1. Need: bare_metal.qz (blocked on `--target freestanding` + `volatile_store_byte`)
10	X.4 — Compiler Internals Cleanup	~~”mir_lower_expr and cg_emit_instr still long chains”~~	COMPLETE — mir_lower_expr 2,446→660 lines (8 handlers), cg_emit_instr 960→285 lines (4 handlers), mir_lower_stmt 1,148→208 lines (9 handlers). tc_expr already done earlier. All 4 major dispatch chains extracted
10.2	X.9 — File Decomposition Round 2	~~”mir.qz 9K lines, typecheck.qz 8.8K lines”~~	COMPLETE — Both mega-files decomposed: mir.qz 9,028→3,109 + `mir_lower.qz` 5,955 (1,364 `mir$` prefixes); typecheck.qz 8,847→3,159 + `typecheck_walk.qz` 5,719 (197 `typecheck$` prefixes). Pattern: satellite imports parent with `import module`, uses explicit `module$` prefixes. No compiler file exceeds 6K lines. Fixpoint verified, QSpec 278/282
10.5	X.8 — String Comparison Hygiene	~~”== on strings is pointer comparison, .eq() is content”~~	COMPLETE — Two-part fix: (1) Compiler source audit (3 rounds, 20+ `==`→`.eq()` bugs fixed in mir.qz, resolver.qz, typecheck.qz, typecheck_registry.qz; 66 `.eq(...)==1` verbosity instances cleaned). (2) Operator fix: `==`/`!=` on strings now emits `str_eq` (memcmp-based content comparison) instead of `icmp eq` (pointer comparison). Extended `mir_is_string_expr` with 3 new detection paths: user-defined function return types from AST, NODE_INDEX string container elements, `str_split`/`str_chars` result tracking. Fixed `is_string_op == OP_SUB` → `is_string_op == 1`. 35 adversarial tests in `string_equality_spec.qz`. QSpec: 277/277

P2: Compiler Engineering

Make the compiler itself solid.

Rank	Phase	Gap Addressed	Current State
11	FP — Fixpoint Parity & True Self-Hosting	~~”C bootstrap required, no optimized release”~~	COMPLETE — C bootstrap retired. `rake quartz:fixpoint` verified (1,466 functions, gen1==gen2 identical). ~~Fixpoint blocked by P.5 bootstrap~~ FIXED — root cause: `str_find(param_type, "String") >= 0` in `mir_is_string_expr` matched `Vec<String>` as string var, causing `enum_names == 0` to emit `str_eq` on Vec handle → SIGSEGV in `qz_str_get_len`. One-time bootstrap IR surgery patched 2 poisoned `str_eq(x,0)` sites in gen1.ll
12	P.2 — Incremental Compilation	~~”Whole-program compilation only”~~	TIER 0 + TIER 1 + TIER 2 + AST CACHE COMPLETE — Tier 0: pre-resolution quick-check (9s → 23ms, 400× speedup). Tier 1: per-module codegen caching with dep graph + interface hash early cutoff. Tier 2: selective TypeCheck + MIR skip for unchanged modules (10.4s → 6.9s, 34% reduction, 1367/1375 functions skipped). Tier 2 correctness fix: seed modules always propagate to direct dependents (MIR inlines bodies cross-module). incr_tier2_spec 7/7 pass (2 previously pending tests activated). Binary Vec serialization intrinsics + AST cache V3. Known: e-graph optimizer 2-cycle oscillation (pre-existing)
13	P.5 — Compiler Performance	~~”Haven’t profiled, no string interning, no arena AST”~~	COMPLETE — 3 rounds, 15.6s → 2.3s (85% total reduction). Round 1: String interning (15.6s → 9.7s, 38%). Round 2: MIR/codegen HashMap fixes (12.6s → 7.3s, 42%). Round 3 (P.5.TC): Typecheck HashMap optimization — TC 4.5s → 490ms (89% reduction, 9.1× speedup). 13 HashMaps in typecheck_registry.qz (func/struct/enum/trait/impl name+suffix maps) + typecheck.qz (alias/newtype maps). Two-suffix approach: first-$ suffix (UFCS `Type$method`) + last-$ suffix (bare `method`). First-wins registration semantics. `tc_find_matching_overload` uses HashMap + bounded forward scan for arity matching. `tc_lookup_impl` uses composite `trait$type` keys with base-trait fallback for generics. `tc_lookup_trait` strips `<...>` generics before lookup. New profile: resolve 48% (1.1s), TC 21% (490ms), MIR 19% (451ms), codegen 10% (235ms). Next frontier: resolve optimization.
14	M.R — Memory Model Remaining	~~”Escape analysis, Bool as i1”~~	COMPLETE. M.R.1/2/3/5/6/7/8 all done (f32_vec removal, escape analysis, enum discriminants, inline structs, register passing, Bool narrow type, stack alloc for @value struct returns)
15	P.3 — Separate Compilation	~~”No per-module .o files”~~	✅ CORE COMPLETE (Mar 2, 2026). `--separate` flag emits per-module `.ll`, parallel `llc`, `.o` caching. `quake build:separate` builds compiler from 40 modules. 6 QSpec tests.

P2.5: Execution Plan — Stack-Ranked with Parallel Tracks

All remaining work stack-ranked by priority. MAIN = requires main branch (core compiler changes). WORKTREE = safe for anti-gravity parallel sessions. Dogfood checkpoints after each tier.

Tier 0: Safety Foundation (fix the floor before building higher)

#	Phase	Description	Track	Why This Order
1	FIX.1 — vec_get OOB Panic — COMPLETE	All 4 OOB sites (MIR_INDEX, MIR_INDEX_STORE, vec_get, vec_set) now panic with `"index out of bounds: index N, size M"` to stderr + backtrace + abort. `vec_get_unchecked` and `MIR_INDEX_RAW`/`MIR_INDEX_STORE_RAW` unchanged. `@qz_bounds_panic` helper in codegen_runtime.qz. 15 new tests in bounds_check_spec.qz. Cascade fixes: `.size` on Int-typed vars reads capacity (offset 0) not size (offset 1) — fixed in `mir_collect_captures_walk` (2 sites), `csv.qz` (3 sites), `nested_generics_comprehensive_spec.qz` (1 site). `clone_with_unquote` crash on `-1` sentinel (parser’s “no else” marker) — added guard. Net result: QSpec +3 (302→305).	MAIN	Every test, benchmark, and program hits vec_get. Silent 0 is a correctness landmine. Fix before writing any new vector code.
2	FIX.7 — Dead HIR Pass — COMPLETE	Deleted `hir.qz` (925 lines). Removed `import hir` and disabled Phase 5 comments from `quartz.qz`. Cleaned stale HIR references from op_constants.qz, ast.qz, mir.qz doc comments. Fixpoint verified.	WORKTREE	✅ Clean the house before adding rooms.
3	FIX.3 — Time Library — COMPLETE	Real calendar arithmetic: `is_leap_year`, `days_in_month`, `days_in_year`, `epoch_to_year/month/day/hour/minute/second`, `day_of_week` (Zeller’s congruence), `time_month()`, `time_day()`. Duration struct for time arithmetic. 42 tests across 13 describe blocks in `stdlib_time_spec.qz`. Known dates verified: epoch 0 = 1970-01-01 Thursday, Y2K = Saturday, 1000000000 = 2001-09-09.	WORKTREE	✅ No compiler changes.

Dogfood checkpoint A: After FIX.1 — audit all existing tests that relied on vec_get returning 0 for OOB. Some tests may have been silently wrong.

Tier 1: Test Hardening (you can’t prove correctness without adversarial tests)

#	Phase	Description	Track	Why This Order
4	TEST.1 — Spec Hardening Sweep — PARTIAL	6 critical files hardened (+67 tests): ffi_spec 5→15, for_in_typed_spec 2→15, union_types_spec 5→15, vec_sort_spec 5→16, user_macros_spec 5→15, auto_vectorize_spec 2→15. bounds_check_spec (15 new), closure_stress_spec added. Remaining: ~180 spec files still have <10 tests. Target: no spec file under 15 tests.	WORKTREE	Pure test addition. No compiler changes. Can run in parallel with anything.
4.5	TEST.2 — Specification as Proof — COMPLETE	216 new tests across 8 phases. Phase 0: Error Code Catalogue — `error_codes_spec.qz` (30 active + 5 pending covering 34 QZ error codes). Phase 1: Safe Navigation — `safe_navigation_spec.qz` (14 active + 1 pending, 5 dimensions). Phase 2: Adversarial Hardening — 4 files (integers 17, strings 22, collections 14, control flow 18 = 71 tests). Phase 3: Cross-Feature Interaction — 5 files (closures×structs 7, match×safety 6+1p, generics×closures 10, iter×match 8, defer×safety 8 = 40 tests). Phase 4: Error Message Quality — `error_quality_spec.qz` (16 active + 1 pending). Phase 5: Property-Based Laws — `property_laws_spec.qz` (16 tests: commutativity, identity, De Morgan, Option laws, Vec roundtrip). Phase 6: Feature Completeness — +30 tests in existing files (multiclause_def +6, macro_parsing +3, type_inference +5, ufcs +3, generator +4, newtype +3, string_interpolation +3, impl_trait +3). Phase 7: `it_pending` audit — all 137 pending tests verified with blocking reasons. Phase 8: Verification — 360/367 files pass (7 pre-existing). Compiler bugs discovered: 3-closure struct capture codegen crash, TC exhaustiveness type-handle-vs-kind bug, QZ0303 emitted as QZ0200, QZ1202→QZ1203, `?.` field validation missing. QSpec total: 367 files, 5,307 active tests, 137 pending.	WORKTREE	✅ Specification as formal proof. Changing any semantic behavior now requires changing tests.
5	FIX.4+5+5b — Pre-Existing Test Failures — COMPLETE	295/341 → 348/348 (ALL tests pass). FIX.4: 3 bugs fixed (Drop recursion, E-graph CSE, Quake runner flakiness), ~50 aspirational tests → `it_pending`. FIX.5: 9 test files fixed (for_in sum, exit code mod 256, F64 literal, parser validations), 21 tests marked `it_pending`. FIX.5b: 7 remaining failures fixed — root cause: implicit-return struct literals parsed as struct destructuring (parser infinite loop). Added explicit `return` in std/net/ (tcp, tls, buffered_net, http_server) + shared/qzi.qz. Also fixed `@cfg` on `extern "C" def` (parser missing `TOK_EXTERN` handling). Fixpoint verified.	WORKTREE	✅ Zero unexplained failures.
5.5	FIX.6b — Vec Multi-Word @value Struct Runtime — COMPLETE	All runtime vec functions fixed for `Vec<@value Struct>` where inline structs span multiple i64 words. C runtime (`quartz_runtime.c`): 13 functions — `vec_push/pop/get/set/get_unchecked/set_unchecked/contains/index_of/insert/remove/sort/sort_by/reverse` — all get `ew <= 8` single-word guard + multi-word path using `memcpy`/`memcmp` with `h[3]` (elem_width). LLVM runtime (`codegen_runtime.qz`): 4 functions — `qz_vec_remove/insert/contains/index_of` — single/multi branching, multi-word path with `memcpy`/`memcmp`. `vec_insert` grow also fixed (`mul i64 %newcap, %ew` instead of hardcoded 8). 7 new tests in `inline_struct_vec_spec.qz` (pop/remove/insert with 2/3-field structs, push-pop-push cycle). QSpec 348/354 (no regressions). Fixpoint verified.	WORKTREE	✅ Runtime correctness for @value struct vectors.

Dogfood checkpoint B: ✅ Full quake qspec — 360/367 pass (7 pre-existing). 5,307 active tests, 137 pending (all with documented blocking reasons). TEST.2 Specification as Proof complete. Achieved Mar 9, 2026.

Tier 2: Language Features — Quick Wins (simplest first, each informs the next)

#	Phase	Feature	Track	Why This Order
6	LF2.1 — Or-Patterns — COMPLETE	`Red \| Blue => ...` — Multiple patterns sharing a match arm body. NODE_OR_PATTERN (kind=81). Parser: `\|` between patterns + arm boundary detection fix. TC: validate sub-patterns, exhaustiveness coverage. MIR: emit comparison chain (both expr and stmt match). 33 tests in or_pattern_spec.qz. QSpec: 333/340. Fixpoint verified.	MAIN	✅ First LF2 feature complete.
7	LF2.3 — Range Step — COMPLETE	`for i in 0..100 step 2` — Step value for range iteration. `step` as contextual keyword (not reserved). Negative step for reverse (`10..0 step -1`). Direction-aware condition (compile-time for constant step, runtime arithmetic for variable step). Works in for-loops and all 3 comprehension types (list/set/map). 15 tests in range_step_spec.qz. Fixpoint verified.	MAIN	✅ Second LF2 feature complete.

Dogfood checkpoint C: Use or-patterns in compiler source (match arms with shared bodies — there are dozens). Use range step anywhere we have i = i + 2 inside a for loop. Adversarial tests: or-patterns with bindings, with guards, nested, in for-in, with rest patterns. Range step: zero step (error), negative step, step larger than range, empty range with step.

#	Phase	Feature	Track	Why This Order
8	LF2.2 — Pattern Binding in Conditionals ✅	`if Some(v) = expr` — Conditional pattern matching without full `match`. No `let` keyword (consistent with const-by-default). Binds pattern variables in if-body scope. `else`/`elsif` for non-match. All pattern types supported. 19 QSpec tests.	MAIN	Builds on match infrastructure just extended for or-patterns. Unlocks eliminating verbose single-arm match blocks.
9	LF2.6 — Spread Operator ✅	`[...a, ...b]` — Collection spreading in array literals. NODE_SPREAD (kind=82). Parser: `...expr` prefix after `[` or `,`, parse error with list comprehension. TC: unwrap spread for element type inference. MIR: `mir_lower_array_with_spread` — dynamic `vec_new` + `vec_push`/loop (reuses existing intrinsics, no codegen changes). 7 walker sites (TC capture, MIR capture, liveness, macro expand ×2, resolver ×2). 15 tests in spread_operator_spec.qz. Fixpoint verified.	MAIN	✅ Fourth LF2 feature complete.

Dogfood checkpoint D: Use if Some(v) = expr everywhere in compiler that currently does match ...; Some(v) => ...; _ => ; end for single-arm option checks. Use spread in test helpers that build vectors. Adversarial tests: nested pattern binding, pattern binding with or-patterns, spread of empty vec, spread in function call args, spread + rest in same expression.

Tier 3: Correctness — Hardening the Core

#	Phase	Description	Track	Why This Order
10	FIX.2 — Unicode Awareness — COMPLETE	Default string ops codepoint-based; explicit `str_byte_` for byte-level. Phase 1: 6 byte-level intrinsics + runtime. Phase 2: Compiler migrated to `str_byte_`. Phase 3: Codegen flipped + all String `.size`→`str_byte_len()` across 38 compiler files. Phase 4: stdlib/tools/spec migrated — `std/string.qz` + 41 std/ files + tools/ use byte-level internally. UFCS `.byte_at()/.byte_slice()/.byte_len()/.byte_find()/.bytes()` on String. `unicode_byte_spec.qz` + `unicode_codepoint_spec.qz` tests. Phase 5: INTRINSICS.md + QUARTZ_REFERENCE.md updated with dual-level API docs. Bug fixes: NODE_INDEX→NODE_CALL rewrite stale `rights[node]` (5 sites) caused `ast_call_get_default_mask` to misinterpret index handle as named-args bitmask; `qz_str_find_utf8` Option tag inversion (Some=0/None=1 convention). 89 files changed, 3705+/1752-. QSpec 329/348 (0 regressions). Fixpoint verified.	MAIN	Touches string builtins deeply — codegen_runtime changes. Must be on main.
11	FIX.5 — Cross-Platform Stdlib — COMPLETE	8 phases, all platform blockers resolved. Prior work: @cfg-gated errno, Addrinfo, get_host_target, Quakefile linker flags, event_loop (kqueue+epoll), REPL LLVM paths. New (Mar 9, 2026): Phase 1-2 (CRITICAL codegen): `cg_is_linux()` + `cg_stderr_symbol()`/`cg_stdout_symbol()` helpers — 6 emission sites fixed (`@__stderrp`→`@stderr`, `@__stdoutp`→`@stdout`). `eprint_int` + `eputs` intrinsic stderr symbol. `stat` st_size offset 96→48, `readdir` d_name offset 21→19. `g_codegen_target` global set from all 4 codegen entry points. Phase 3: tcp.qz `_tcp_make_sockaddr` @cfg-gated (macOS sin_len vs Linux sin_family layout), `_addrinfo_ai_addr_offset()` (32→24), `resolve_host` uses helper. Phase 4: `O_NONBLOCK` @cfg (4→2048) in socket.qz, `set_nonblocking` @cfg in http_server.qz. Phase 5: Quakefile `_regex_lib_flag()` (.dylib macOS → .o -lpcre2-8 Linux). Phase 6: benchmarks/run.sh Linux RSS profiling (`/usr/bin/time -v`). Phase 7: runtime comment cross-platform. Phase 8: 14 IR-level tests in cross_platform_stdlib_spec.qz (all green). `_dyld_get_image_name` NOT used anywhere — stale ROADMAP entry. PCRE2 via `lib/regex.c` wrapper (portable). Deferred: http_server.qz full Linux port (needs epoll path for kqueue), Linux validation on QEMU/OrbStack. Fixpoint verified, QSpec 346/354 (no regressions).	WORKTREE	✅ All critical platform blockers fixed.

Dogfood checkpoint E: After Unicode — audit all string operations in compiler source for byte-vs-char assumptions. ✅ After cross-platform — build and test on Linux VM. Run full QSpec on Linux. (FIX.5 codegen/stdlib complete; Linux validation on QEMU/OrbStack remaining.)

Tier 4: Language Features — Medium Complexity

#	Phase	Feature	Track	Why This Order
12	LF2.4 — Named Arguments ✅	`connect(port: 8080, host: "localhost")` — Parser: `name: expr` in call args with lambda disambiguation. TC: reorder+validate+default-fill via registry param names + AST handles. Zero MIR/codegen changes. 18 QSpec tests.	MAIN	DONE
13	LF2.7 — impl Trait Returns ✅	`def foo(): impl Trait` — Opaque return types. Parser: `impl` keyword in type position produces `"impl TraitName"` annotation. TC: infer concrete type from return exprs, verify trait impl, register in parallel arrays. UFCS: resolve `"impl "` prefix to concrete type at call sites. Same-type constraint enforced. 8 QSpec tests.	MAIN	DONE

Dogfood checkpoint F: Named args in compiler where function calls have >3 params and argument meaning is unclear. impl Trait returns for iterator-returning functions in std/iter.qz. Adversarial tests: named args out of order, mixed named+positional, duplicate names (error), unknown names (error), impl Trait with multiple traits, impl Trait in struct field (error?), impl Trait return type mismatch.

Tier 5: Language Features — Hard (architectural changes)

#	Phase	Feature	Track	Why This Order
14	LF2.8 — Multi-Clause Function Heads ✅	Elixir-style repeated `def` with patterns in param position. Resolver-level desugar to match expression. Supports integer/bool/string literals, wildcards, multi-param dispatch, `when` guards. 19 QSpec tests.	MAIN	DONE
15	LF2.5 — Generator Functions ✅	`yield` keyword. State machine compilation: constructor + `$next` function with state dispatch. All locals stored in heap state struct. Integrates with Iterator protocol via `impl Iterator<T>` return type. Supports yield in while/for loops, if/else branches, parameterized generators. 13 QSpec tests.	MAIN	DONE

Dogfood checkpoint G: Multi-clause def for recursive algorithms in compiler (const eval, pattern dispatch). Generators for sequential-production patterns in std/. Adversarial tests: overlapping patterns in function heads, non-exhaustive heads (error), generator with no yield (error?), generator with yield in loop, nested generators, generator + pattern binding, generator cancellation/cleanup.

Tier 6: Type System Completion

#	Phase	Description	Track	Why This Order
16	FIX.6 — H-M Type Inference Completion	COMPLETE: Phase 1 (constraint propagation): pending ptype registration at NODE_LET + `tc_resolve_pending_ptype`. Phase 2 (closure inference): bidirectional param injection. Phase 5 (list comp types): element type from body. Phase 6 (error messages): QZ0203/QZ0204. Phases 3-4 structurally handled by existential erasure. Dead code cleanup: 728 lines removed from infer.qz (1,970→1,242) — unused generalization/instantiation subsystem, test harness, dead wrappers. Two systems coexist by design: ptype annotations (UFCS dispatch workhorse) + infer.qz (expression inference fallback). Row constraints deferred until record types land. 16 inference tests + 6 error tests. Fixpoint verified.	MAIN	All language features above may reveal new inference requirements. Do this after features settle, informed by real usage.

Dogfood checkpoint H: Remove explicit type annotations in compiler source that inference should now handle. Run adversarial type inference suite. Test target: 50+ inference edge cases.

Tier 7: Targets & Backends

#	Phase	Description	Track	Why This Order
17	TGT.2 — C Backend — COMPLETE	All 7 phases done + FIX.6b runtime multi-word fix. C runtime library (`runtime/quartz_runtime.c`, ~1200 lines) + codegen (`codegen_c.qz`, ~1500 lines). All 32 MIR instruction kinds + 100+ intrinsics. Closure dispatch via `qz_call_0..5`. `quake build:c` + `quake test:c` (35/35). Self-compilation achieved: C-compiled compiler produces byte-identical LLVM IR to LLVM-compiled compiler (890K lines, diff empty). Key fixes: `find` intrinsic (Option wrapper vs raw element), `to_s`/`to_str` (added `qz_to_str` runtime discriminator), `str_len` (strlen→qz_str_len), `str_eq` (lazy string emission). argc/argv forwarding. FIX.6b: 13 C runtime vec functions fixed for multi-word `@value` struct elements (`ew <= 8` / multi-word branching with `memcpy`/`memcmp`). Design doc: `docs/design/C_BACKEND.md`.	WORKTREE	✅ Bootstrap independence achieved.
18	TGT.1 — WASM Target — COMPLETE	All 7 phases done (0-6). Phase 0: Toolchain validated (wasi-sdk, wasmtime, llc wasm32). Phase 1: Libc wrapper system — 16 `@__qz_` wrappers (malloc, realloc, memcpy, memcmp, memset, strlen, puts, write, fread, fwrite, qsort, strncpy, getcwd, fseek, ftell, strncmp) with i64→i32 truncation on wasm32, `alwaysinline` on native for zero overhead, ~245 call sites renamed across 4 codegen files. Phase 2: Runtime fixes — `to_str` threshold bypassed on wasm32, stderr/stdout globals gated, backtrace gated, capture_output stubs, `%lld` format strings, `eputs` uses `write(2,...)` on WASI. Phase 3: C runtime compiles for wasm32 (`#ifdef __wasm__`). Phase 4: `build:wasm`/`test:wasm` Quake tasks. Phase 5: Stdlib `@cfg(not: os: "wasi")` gating (socket.qz, event.qz, tcp.qz, http_server.qz, event_loop.qz). Phase 6: wasi_spec expanded 6→25 tests. End-to-end verified*: hello world, arithmetic, str_from_int, Vec ops, recursion, pattern matching, for-in — all running on wasmtime. Phase 7 (self-compilation) deferred as stretch goal.	MAIN	✅ Quartz programs compile and run on WASM runtimes.

Dogfood checkpoint I: ✅ C backend DONE — compiled the compiler itself through C backend, output byte-identical to LLVM. ✅ WASM target DONE — Quartz programs compile, link, and run on wasmtime (WASI Preview 1). 16 libc wrappers, stdlib @cfg gating, 25 QSpec tests.

Tier 8: Developer Experience

#	Phase	Description	Track	Why This Order
19	DX.1 — World-Class Debugger ✅	COMPLETE (Mar 9-10, 2026). 7 phases implemented (1-5.2 + 1.7). Phase 1: `!dbg` on ALL instructions (was: calls only), terminators, fn_entry, column info. Phase 1.7: 526 intrinsic call sites annotated across 16 categories. Phase 2: `@llvm.dbg.declare` for all params/locals, 4 DIBasicTypes (Int/Bool/F64/String), DILocalVariable nodes. Phase 3: DICompositeType for 31 structs with DIDerivedType members + pointer wrappers for heap structs. Phase 4: per-module DIFile nodes (~38 files), DISubprogram scope/file per module. Phase 5.1: DISubroutineType with proper return+param types, deduped by signature. Phase 5.2: Enum DWARF debug metadata — simple enums get `DW_TAG_enumeration_type` + `DIEnumerator` per variant; payload enums get `DW_TAG_structure_type` with tag+payload members + IR comment variant mapping. Built-in `Option`/`Result` always emitted. `DIBasicType "i64"` base type. MIR enum_defs pipeline (6 accessors in mir.qz, populated in mir_lower.qz). 8 QSpec tests in `enum_debug_spec.qz`. 355,809 `!dbg` annotations in self-compilation IR. Fixpoint verified, QSpec no regressions, `opt -passes=verify` clean. Deferred: Phase 5.3 (lldb formatters), Phase 6 (separate compilation debug).	MAIN	✅ World-class lldb integration achieved.
20	DX.2 — REPL — MVP COMPLETE	`tools/repl.qz` (~280 lines). Read-wrap-compile-run loop via lli. State accumulation (defs, structs, enums, imports persist across lines). Multi-line input (detects unclosed blocks, `..>` prompt). Commands: `:help`, `:quit`/`:q`, `:clear`, `:state`. Expression auto-print. Error recovery. Cross-platform lli discovery. `quake repl` task. Remaining: history (readline/linenoise), tab completion, `:type` command.	WORKTREE	Zero impact on compiler core. Separate tool binary.

Final: Specification as Mathematical Proof

#	Phase	Description	Track	Why Last
21	TEST.2 — Specification as Proof	Final comprehensive pass after all features. Every language feature gets: (1) happy path, (2) edge cases, (3) adversarial inputs, (4) cross-feature interaction, (5) error message quality. Target: changing any semantic behavior REQUIRES changing tests. The spec suite becomes the formal definition of the language — mathematical proof by exhaustive enumeration.	BOTH	The capstone. After every feature exists and is dogfooded, lock it down. Every behavior is specified. Every corner is tested. Every error message is verified. Changing the language becomes easy to implement but impossible to do silently — the tests catch everything.

Parallel Execution Map

MAIN                              WORKTREE (Anti-Gravity)
──────────────────────────────    ──────────────────────────────
#1  vec_get OOB panic ✅     ←→   #2  Dead HIR pass ✅
                                   #3  Time library ✅
#6  Or-patterns ✅           ←→   #4  Spec hardening (partial) ✅
#7  Range step ✅                  #5  Pre-existing failures ✅
  → dogfood C                      #5b Zero-tolerance QSpec ✅ (348/348)
#8  Pattern binding ✅       ←→   #11 Cross-platform stdlib ✅
#9  Spread operator ✅
  → dogfood D
#10 Unicode awareness ✅     ←→   (continue #4, #11)
#12 Named arguments ✅       ←→   #17 C backend ✅ (self-compile!)
#13 impl Trait returns ✅
  → dogfood F
#14 Multi-clause def ✅
#15 Generators ✅
  → dogfood G
#16 H-M completion ✅             ←→ #20 REPL (MVP) ✅
#18 WASM target ✅ (wasmtime!)
#19 Debugger ✅               ←→   #21 Final spec proof pass

P3: Platform & Ecosystem (DEFERRED)

Do not start any of this until P2.5 is complete and the language is frozen and battle-tested.

Phase	Gap Addressed	Current State
E.2 — Package Manager	”No package manager”	Not started. Intentionally deferred — syntax changes would invalidate everything
E.1 — LSP Server	”No editor intelligence”	Not started. Deferred — any syntax change requires LSP rewrite
W.4 — Website + Launch	”No public presence”	Not started. Deferred until language is solid
W.8 — Launch Blog Post	”No public narrative”	Not started
STD — Standard Library	”Thin stdlib, relies on intrinsics”	COMPLETE — STD.1-8 done + NET.1-6 networking/TLS/HTTP + std/shell.qz (shell_capture/ok/exit/run) + LEO additions: std/iter.qz (enumerate/zip adapters), std/vec.qz (first/last/map/filter)
E.6 — Quake (Task Runner)	~~“Ruby Rake dependency for build workflows”~~	COMPLETE — 20 tasks (19 ported + lint task added Mar 5). 284/284 QSpec green through Quake, docs/QUAKE.md shipped

LEO: Language Ergonomics Overhaul (Mar 3, 2026) ✅ COMPLETE

Pre-freeze cleanup: unified impl, operator traits, iterator protocol, Option<T> returns, first-class tuples, destructuring (tuple + struct + vec), and stdlib additions. All 11 phases + 6 worktree tasks complete. Language freeze target reached.

Parallel Track (Worktree Dogfooding):

Task	Description	Status
W.1	Documentation fixes (6 errors)	COMPLETE (07bb3c6)
W.2	`.eq()` → `==` (169 occurrences)	COMPLETE (fb71582)
W.3	`.concat()` → `#{}` interpolation (273 changes, 21 files)	COMPLETE (4d95260)
W.4	`0 - 1` → `-1` (97 instances)	COMPLETE (fb71582)
W.5	`while` counter → `for i in 0..N` (~50 sites, ~15 files)	COMPLETE — migrated simple counted loops where counter is not modified inside loop body. Immutable for-in counter is sufficient for these patterns.
W.6	Magic ASCII → char literals (359 changes, 23 files)	COMPLETE (4d95260)
W.7	Drop for StringBuilder	COMPLETE (deferred) — investigated, decision: defer until compiler Drop semantics are refined. No code changes needed now.

Main Track (Compiler Changes):

Phase	Description	Depends On	Status
2	Bool return types for 37 predicates	—	COMPLETE (69c3354)
3	`extern fn` → `extern def` (149 occurrences)	—	COMPLETE (2ddbc2f)
4	Default struct field values (`field: Type = expr`)	—	COMPLETE (d90e925, merged 14b3e83)
5	impl unification (KEYSTONE) — inherent `impl Type`, self injection, @field, `extend` as alias	—	COMPLETE (4c0a28d, ea3cccd)
5.6	Migrate 50 `extend` blocks to `impl` syntax	Phase 5	COMPLETE (ea3cccd) — 46 blocks across 27 files
6	Operator traits (Add, Eq, Ord, Index)	Phase 5	COMPLETE (b08aa7b) — Eq/Ord renamed to `op_*`, 6 new traits (Add/Sub/Mul/Div/Mod/Index), `@derive(Eq)` enables `==`, TYPE_BOOL for comparisons, op_index dispatch, NODE_BINARY struct_name propagation. 12 new tests in operator_traits_spec.qz
7	Iterator protocol (`Iterator<T>`, lazy adapters, terminals)	Phases 5, 6	COMPLETE — formal `Iterator<T>` trait, closure-based lazy adapters (Map/Filter/Take/Skip/TakeWhile), 10 terminal ops, VecIter/RangeIter, for-in integration, field-assign offset bug fix. 38 tests in iterator_protocol_spec.qz
7.5	Generic UFCS dispatch for Iterator bounds	Phase 7	COMPLETE — closure-based dispatch for `<T: Iterator>` bounded generics. PASS 0.9.1 tags Iterator-bounded entries. Function bodies: Iterator params become closures, `.next()` → indirect call, `for-in` → `lower_closure_iteration`. Call sites: `synthesize_next_closure` auto-generates `-> arg.next()` lambdas. Fixed `tc_lookup_impl` generic trait matching (`Iterator<Int>` matches `Iterator` bound). 8 tests in generic_ufcs_dispatch_spec.qz. Fixpoint verified
8	`Option<T>` returns for fallible operations	Phase 7	COMPLETE — In-place migration (no `_opt` variants, no sentinels). `str_find` → `Option<Int>`, `hashmap_get` → `Option<T>`, `vec_pop` → `Option<T>`, `vec_index_of` → `Option<Int>`, `regex_match_start`/`regex_match_end` → `Option<Int>`. New `str_contains` intrinsic. Codegen helpers `cg_emit_option_some_inline`/`cg_emit_option_none_inline`. Two-stage bootstrap: eliminated all compiler self-dependency on changed functions before changing codegen. ~80 call sites migrated across compiler + stdlib (json, toml, net, qspec). Fixpoint verified
9a	First-class tuples	Phase 5	COMPLETE — `(expr, expr)` construction, `.0`/`.1` typed element access, `(T1, T2)` type annotations. NODE_TUPLE_LITERAL (kind=77), TYPE_TUPLE (53), `g_tuple_elem_types` registry for element types. Parser, typecheck, MIR lowering, all auxiliary passes. 10 tests in tuple_spec.qz. Fixpoint verified
9b	Tuple destructuring	Phase 9a	COMPLETE — `var (a, b) = expr` via NODE_LET_DESTRUCTURE (kind=78). Parser detects `var (` pattern, typecheck validates arity + binds element types, MIR lowers to temp + load_offset per binding. All auxiliary passes (capture walker, liveness, resolver). 10 tests in destructuring_spec.qz. Fixpoint verified
9c	Struct & Vec destructuring	Phase 9b	COMPLETE — `Point { x, y } = expr` (type required), `var { x, y } = expr` (inferred), `[a, b, ..rest] = vec`. Field renaming (`x: px`), partial (`x, ..`), match arm patterns, for-in patterns. NODE_STRUCT_DESTRUCTURE (kind=79), NODE_VEC_DESTRUCTURE (kind=80). Parser: 2 helpers + 4 integration points. TC: struct field validation, Vec rest ptype. MIR: `mir_emit_load_offset` for field access. Resolver/capture walker/liveness extended. 12 tests in struct_destructure_spec.qz. Fixpoint verified
10	stdlib additions (vec_clone, is_upper/lower, iterators, vec utils)	Phases 7, 8, 9a	COMPLETE — 10.1: `vec_clone` intrinsic (shallow memcpy clone), `is_upper`/`is_lower` character intrinsics, 32-byte Vec header migration (fixed array literals, `qz_vec_new`, `qz_vec_reverse`, `qz_readdir`, `qz_vec_load`, `vec_slice` — all now store `elem_width` at `header[3]`). 10.2: `iter_enumerate` (yields `(index, value)` tuples), `iter_zip` (yields `(a, b)` tuples). 10.3: New `std/vec.qz` with `vec_first`, `vec_last`, `vec_map`, `vec_filter`. Fixpoint verified

LFA: Language Freeze Audit (Mar 4, 2026) — ALL PHASES COMPLETE (except C.6, G deferred)

Post-LEO second pass: eliminate remaining ergonomic debt before language freeze. Bool hygiene, Option pattern modernization, dogfooding cleanup, collection API unification, API completeness, documentation fixes, as_int()/as_string() reduction.

Phase A: Bool Hygiene — == 1/== 0/== true/== false Elimination + Predicate Return Types — COMPLETE

Sub-Phase	Scope	Status
A.1	`self-hosted/middle/typecheck*.qz` — 5 files, ~72 replacements	COMPLETE
A.2	`self-hosted/backend/` — 10 files (codegen, mir, mir_lower, egraph_opt, etc.), ~112 replacements	COMPLETE
A.3	`self-hosted/frontend/` — parser.qz (~226), derive.qz (~11), macro_expand.qz (~1)	COMPLETE
A.4	`self-hosted/resolver.qz` + `quartz.qz` + `shared/build_cache.qz` — ~24 replacements	COMPLETE
A.5	`std/` + `tools/` + `spec/` — ~266 replacements across ~50 files	COMPLETE
A.6	`check_bool_hygiene` in `tools/lint.qz` — Tier 1+2 heuristic, 14 tests	COMPLETE
A.7	Predicate return types + anti-pattern completion — ~55 function signatures `: Int` → `: Bool`, ~230+ anti-pattern call sites cleaned	COMPLETE

A.7 Detail: All compiler-internal predicate functions (is_*, has_*) now return : Bool with return true/return false. Covers: ast.qz (6), parser.qz (3), derive.qz (3), typecheck.qz/typecheck_builtins.qz/typecheck_registry.qz/typecheck_util.qz (12), liveness.qz (2), infer.qz (5), mir.qz (13), mir_lower.qz (1), codegen_runtime.qz (3), codegen_util.qz (5), resolver.qz (3), json.qz+json/lexer.qz+json/parser.qz (10), http_server.qz (2), bspec.qz (2). Anti-pattern cleanup: pred() == 1 → pred(), pred() == 0 → not pred() across ~25 files. Resolves key discovery #1 from A.1-A.6 — all predicates now return Bool, not works everywhere. Skipped: typeenv_is_mutable (3-valued with -1 sentinel), infer_has_errors (returns count). QSpec 362/367, fixpoint verified.

Key Discoveries (A.1-A.7):

~~The not operator requires a Bool operand (typecheck-enforced). ~100 remaining == 0/== false patterns on Int-returning functions BLOCKED on language decision~~ RESOLVED by A.7 — all predicate functions now return Bool, not works with all predicates.
$assert macro uses not internally — can’t pass Int-returning expressions directly (must keep $assert(int_func() == 1)).
Closure call return types not tracked through not — not predicate(x) where predicate: Fn(Int): Bool fails with QZ0200. Must use predicate(x) == false instead.

Safe transformations applied (~950+ total across ~95 files):

if pred() == 1 → if pred() — always safe, if accepts Int truthiness
x == y == false → x != y — always safe
== true removal — always safe
pred() == false → not pred() — safe for all Bool-returning functions
pred() == 0 → not pred() — safe for all Bool-returning functions (all predicates now return Bool after A.7)

Lint Rule (A.6): check_bool_hygiene() in tools/lint.qz — text-based heuristic scanner with string/comment awareness. Tier 1: flags == true/== false/!= true/!= false (zero false positives). Tier 2: flags known_pred() == 1/== 0 using predicate name allowlist (is_, has_, contains, starts_with, ends_with, _eq, exists, closed). 14 tests in lint_bool_hygiene_spec.qz. Wired into lint_file().

Phase B: Option Pattern Modernization — ALL COMPLETE

Sub-Phase	Scope	Status
B.0	Confirm cross-module Option matching works	COMPLETE — verified via existing prelude/option specs. Original “blocked” assessment was stale.
B.1	`std/iter.qz` — 18 sites	COMPLETE — migrated to `match` destructuring. Discovered: Quartz requires `_ =>` wildcard in every Option match. 38/38 iterator tests pass.
B.2	`std/string.qz`, `std/net/http.qz`, `std/net/http_server.qz` — ~30 sites	COMPLETE — QSpec 326/334, 0 new regressions.
B.2+	Deferred std/ Option Match — 11 sites across 6 files	COMPLETE — remaining `option_get` after hashmap_has guards in `linked_list.qz`, `json.qz`, `json/value.qz`, `json/stringify.qz`, `toml/value.qz`, `toml/stringify.qz`. Zero `option_get`/`option_is_some` remain in std/.
B.3	`tools/` — 0 sites	COMPLETE — zero occurrences found. All option_get/option_is_some in tools/ were compiler intrinsic implementations (must not touch).
B.4	`spec/qspec/` — ~250 sites across 35 files	COMPLETE — migrated to match destructuring, `.some?`/`.none?` predicates. Zero `option_get`/`option_is_some` remain in spec/qspec/.

Phase C: Dogfooding Cleanup — C.1-C.5 COMPLETE, C.6 DEFERRED

Sub-Phase	Scope	Status
C.1	`0 - expr` → `-expr` — 153 sites across std/, tools/, spec/	COMPLETE
C.2	`str_eq(a, b)` → `a == b` — 104 sites across std/, tools/, spec/	COMPLETE
C.3	`str_concat(a, b)` → `a + b` — ~1,071 sites (17 reverted in std/colors.qz due to codegen)	COMPLETE
C.4	`str_len(s)` → `s.size`, `vec_len(v)` → `v.size` — ~572 sites (~7 remaining)	COMPLETE — After UFCS comprehensive fix (Phases 0-8), all fixable `.size` calls applied. ~7 remaining: `vec_new()` globals without type param, newtype opacity, declared-as-Int enum payloads.
C.5	`vec_push/get/set/pop` → UFCS — ~184 migrated, ~110 skipped	COMPLETE — Migrated across 30 files (6 collections + 24 std/spec files). Zero `vec_push`/`vec_get`/`vec_set`/`vec_pop` remaining in `std/collections/`. ~110 sites intentionally skipped: bare `Int` handles in QSpec infrastructure, BSpec, TOML parser match-arm bindings, Quake task handles, iter.qz VecIter self.data. Can only be migrated after type inference for bare Int handles.
C.6	Redundant type annotations — 51 sites removed	COMPLETE — Removed `var x: Vec<T> = vec_new<T>()` → `var x = vec_new<T>()` across 10 files (typecheck_registry 18, quartz 6, resolver 5, parser 2, typecheck 2, Quakefile 11, quake 4, others 3). Original estimate of 149 over-counted — most spec/ annotations are the sole type source and cannot be removed.

Key Discovery (C.4/C.5): UFCS .size/.push()/[i] originally failed in 5 contexts. UFCS Comprehensive Fix (Mar 4, 2026, Phases 0-8) resolved all fixable contexts:

Phase 0: tc_annotation_to_container_type helper extracted (deduplication).
Phase 1: Generalized annotation fallback beyond NODE_IDENT — tc_infer_expr_type_annotation as tier-2 lookup. Fixes struct field access (e.g., self._data.size in iterator impls).
Phase 2: Function param annotation propagation — tc_scope_bind_full passes param_type_ann. Fixes typed params like items: Vec<Int>.
Phases 3-5: NODE_INDEX, NODE_ARRAY, NODE_LIST_COMP handlers in tc_infer_expr_type_annotation. Fixes words[0].size, array literal .size, list comp .size.
Phase 6: Match arm binding annotation propagation — tc_bind_pattern_variables tracks resolved_anns. With type param safety check for generic contexts.
Phase 7: 14 .size calls re-applied across collections, spec, std.
Phase 8: 7 diagnostic tests in ufcs_inference_spec.qz.
Resolver fix: Trait impl methods now get self type annotation from for_type — fixes UFCS on self.field in trait impl blocks.
NOT FIXABLE (~7 calls): vec_new() globals without type param (no ptype info), newtype opacity (by design), declared-as-Int enum payloads (type erasure).
FIXED: Range-based list comprehensions ([x * 2 for x in 0..5]) — mir_lower_collection() now detects OP_RANGE/OP_RANGE_INCLUSIVE and emits numerical loop instead of vec_len/vec_get. 5 tests in range_listcomp_spec.qz.

Phase D: Collection API Safety — D.1-D.5 COMPLETE, D.6 DEFERRED

Sub-Phase	Scope	Status
D.1	Stack `pop()`/`peek()` → `Option<Int>`	COMPLETE — returns `Option::None` when empty, `Option::Some(val)` otherwise. 10 spec call sites updated.
D.2	Queue `dequeue()`/`peek()`/`shift()`/`first()` → `Option<Int>`	COMPLETE
D.3	Deque `pop_front()`/`pop_back()`/`peek_front()`/`peek_back()` + aliases → `Option<Int>`	COMPLETE
D.4	LinkedList `pop_front()`/`pop_back()`/`peek_front()`/`peek_back()` + aliases → `Option<Int>`	COMPLETE
D.5	PriorityQueue `pop()`/`peek()` → `Option<Int>`	COMPLETE
D.6	Iterator integration — `.iter()` on all collections	COMPLETE — 6 local iterator structs added (StackIter, QueueIter, DequeIter, LinkedListIter, PQIter, SortedMapKeyIter/SortedMapValueIter). 15 tests in `collection_iterators_spec.qz`. Cross-module `.size` on iterator struct fields fixed by UFCS comprehensive fix (resolver trait impl self annotation).

Phase E: API Completeness — COMPLETE (already existed)

All planned additions already exist as builtins: vec_sort, vec_reverse, vec_contains, vec_index_of, str_repeat, str_join, str_pad_left, str_pad_right. Iterator adapters (iter_chain, iter_flat_map, iter_scan) deferred as additive new code.

Phase F: Documentation Accuracy Audit — COMPLETE

Item	Description	Status
F.1	QUARTZ_REFERENCE.md corrections — v5.26 header, removed stale C bootstrap refs, fixed macro docs, corrected str_find/vec_pop signatures, added 4 new sections (Impl Blocks, Tuples, Iterators, v5.26 Breaking Changes), updated stdlib table	COMPLETE
F.2	ARCHITECTURE.md updates — function count (~3,261), line count (~70,445), QSpec test file count (332)	COMPLETE
F.3	Collection documentation — 131-line section in QUARTZ_REFERENCE.md documenting all 6 stdlib collections (Stack, Queue, Deque, LinkedList, PriorityQueue, SortedMap)	COMPLETE
F.4	INTRINSICS.md refresh — complete overhaul from ~40 to ~250+ builtins across 25+ categories	COMPLETE
F.5	DOC.1 QUARTZ_REFERENCE.md Comprehensive Audit — 15 corrections (pipe lambda removal, HashMap Option return, @cfg not:, $debug stderr, eprint implemented, QSpec count, hashmap_delete) + 11 new sections (wildcard/pub imports, @value, loop, not-requires-Bool, @thread_local, —overflow-check, cimport, union/intersection/record types, borrowing). Fixed CLAUDE.md anti-hallucination table (`&x` is valid borrow syntax). Struck 2 stale parser limitation bugs (`&`/`	` both resolved).

Phase G: as_int()/as_string() Reduction — ALL COMPLETE

Item	Description	Status
G.1	subprocess.qz typed globals — replaced 6 `Vec<Int>` single-element cells with typed mutable globals (`var _sub_compiler_str`, etc.), eliminated 19 `as_int`/`as_string` casts	COMPLETE
G.2	Spec file as_int cleanup — most remaining casts are architectural (vec_get return type erasure)	COMPLETE — No actionable casts remain; spec multi-file helpers require `Vec<Int>` for heterogeneous storage.
G.3	std/ as_int patterns — colors.qz spinner `Vec<String>` (11 casts), quake.qz `_executed` `Vec<String>` (1 cast)	COMPLETE — Remaining casts in json.qz, formatter, runner are architectural.
G.4	Compiler as_int/as_string — 310→253 (57 in Round 3, 136 in Rounds 1-2 = 193 total eliminated)	ROUND 3 COMPLETE — Round 3 (typed structs + borrow sources): `ResolverEntry` struct in `compiler_types.qz` replaces `[ast_store, node_id, as_int(name), tag]` array literals — `.ast_store`/`.node_id`/`.name`/`.tag` field access replaces indexed access + `as_string()` across 8 files (resolver.qz, mir.qz, mir_lower.qz, codegen.qz, codegen_c.qz, liveness.qz, quartz.qz, compiler_types.qz). `MirDropEntry` struct replaces `[var_name, type_name, depth]` droppable stack arrays — `.var_name`/`.type_name`/`.depth` replaces `as_string(entry[0])`/`as_string(entry[1])`/`entry[2]`. Borrow source write-side `as_int()` removal in typecheck_walk.qz (3 sites, TC doesn’t check indexed write element types). Key bug found: 3 missed `func_entry[0]`/`func_entry[1]` sites in `mir_infer_expr_type` caused SIGSEGV — array indexing on struct triggers `vec_get` which reads `name` field as data pointer. Round 1 (Phases 1,4,5,6): ConstEvalState struct, mir_lower_stmt extraction, codegen_intrinsics helpers, globals→struct fields. 74 casts across 10 files. Round 2 (Phase 2 + sweep): MirInstr typed string fields, array literal write-side, TC vector retyping. Remaining 253: read-side `as_string(vec[i])` (~110, Vec indexed access returns Int to TC), `as_int_generic` struct storage (~25, EGraph/function lists), `vec_push(as_int(string))` into mixed-type Vecs (~30), HashMap values (~15), struct-to-Int parameter passing (~15), borrow source read-side `as_string()` (~7, blocked by indexed access limitation), MIR internal data structures (~50). Each requires typed Vec element access, union codegen, or generic container improvements. QSpec 346/368, fixpoint verified.

Infrastructure fix: Quake launcher tools/quake.qz — fixed 2>&1 stderr merge bug in compile_quakefile() that corrupted .ll files with compiler warnings. Changed to 2>err_path with separate stderr capture and cleanup.

Future: Research & Moonshots

Phase	Description
R — Refinement Types	SMT-backed static verification
G — GPU Compute	@gpu + NVPTX backend
A — AI Integration	@ai annotations, constrained decoding
V — Dogfooding Vision	Web framework + marketing site in Quartz
ASY — Structured Concurrency V2	Evaluate Go-style goroutines / Zig-style async — no colored functions. Current task_group model is solid foundation

STRESS-PENDING: Pre-Existing Limitations to Fix

Status (Feb 28, 2026): ALL 16 of 16 resolved. Zero it_pending remaining in stress suite. ✅

Macro Subsystem (10 pending → 0 pending) ✅ RESOLVED

#	Limitation	Resolution
~~M1-M8~~	Template macro `#{}` interpolation conflict	FIXED — changed template macro syntax from `#{}` to `${}`. Avoids string interpolation conflict entirely.
~~M9-M10~~	Variadic `unquote_each` hangs	FIXED — `unquote_each` was never implemented (stub only). Added full parser production + expansion logic with separator-to-op mapping (8 operators).

Collections (3 pending → 0 pending) ✅ RESOLVED

#	Limitation	Resolution
C1	Set UFCS `.size()`/`.has()` not resolved	FIXED — used correct intrinsic names (`set_size`, `set_contains`). UFCS not needed.
~~C2-C3~~	List comprehension SIGSEGV	FIXED — was already resolved by prior compiler updates. Tests activated.

Safety Combined (3 pending → 0 pending) ✅ RESOLVED

#	Limitation	Resolution
S1	Defer + assignment syntax not supported	FIXED — parser now detects `ident = expr` after `defer` and uses `ps_parse_assign_or_call`. MIR `defer_scope_pop`/`emit_deferred` use `mir_lower_stmt` instead of `mir_lower_expr`.
S2	Struct created in loop off-by-one	FIXED — test passes correctly.
S3	`default` keyword clash in param name	FIXED — `default` made contextual keyword (only special in select arms).

Remaining: 0 pending ✅ ALL RESOLVED

Completed Phases

All completed phases are preserved in ROADMAP-v5.25.0.md and summarized in CHANGELOG.md.

Phase	Description	Summary
0	Dogfooding Phase 1	Validated closures, defer, HOF intrinsics in self-hosted compiler
1	Fixed-Width Integers	I8/I16/I32/U8/U16/U32/U64 types, FFI compat, @repr(C)
2	Volatile Access	volatile_load/volatile_store intrinsics for MMIO
3	Memory Ordering	Atomic ordering params, fence intrinsic
4	Exhaustiveness Checking	Compile-time match coverage for enum variants
5	Native Floats	F64, F32 with full arithmetic; F32x4/F64x2/I32x4 SIMD
6	Packed Structs	@packed attribute for C-style packed structures
7	Conditional Compilation	@cfg attribute for platform-specific code
8	Const Evaluation	Compile-time const eval, const def, const generics Array<T,N>
9	Inline Assembly	Full inline asm with constraints and clobbers
10	Bit Manipulation	popcount, clz, ctz, bswap intrinsics
11	Dogfooding Phase 2	Final validation with P2P gossip chat
C	Concurrency Sprint	select, try_recv/try_send, blocking ops, Task
S	Sized Storage & SIMD	Narrow params/locals/fields, F32x4/F64x2/I32x4, FMA, shuffle. Gather/scatter done (vector API with `@llvm.masked.gather/scatter`, 8 handlers rewritten). SIMD convert done (8 conversion intrinsics)
B	Benchmark Optimization	Pipeline fix, StringBuilder, LLVM hints, vec unchecked, Polly
T	Multi-Target	C backend COMPLETE (`--backend c` + `codegen_c.qz` + `runtime/quartz_runtime.c`). All 32 MIR kinds, 100+ intrinsics, closure dispatch, self-compilation verified (byte-identical output). `quake build:c` + `quake test:c` (35/35). cimport done (`cimport "stdio.h"` + std/ffi/ stubs). x86_64 cross-compilation done. WASI gating done. extern var done. freestanding done. WASM target COMPLETE — 16 libc wrappers, stdlib @cfg gating, 25 QSpec tests, end-to-end verified on wasmtime
L	Linear Types	Move semantics, borrows, Drop
SC	Structured Concurrency	Scope-bound task groups, cooperative cancellation
CI	Custom Iterators	`for x in struct` via `$next` method
N	Networking & TLS	TCP client/server, TLS/HTTPS (OpenSSL 3.x), HTTP client+server, buffered I/O, timeouts — 41 tests
OPT	MIR Optimization	DCE, TCO, regalloc hints, inlining, e-graph optimizer
GV	Global Variables	Cross-module `var` declarations
GAP	Table Stakes Audit	35 gaps audited, 5 critical found
TS	Table Stakes Impl	21/21 features: loop, usize, raw strings, slices, tuples, macros, etc.
LS	Literal Syntax	Negative indexing, char literals, set comp, ranges, Bytes type
W.1	API Unification	~37 builtins synced, both compilers identical API surface
W.3	Auto-Generated Docs	`tools/doc.qz` generates Markdown API docs for 29 stdlib modules
W.7	CLI Unification	`quartz build/run/check/fmt/lint/doc` commands

| 9 | Fix QSpec Failures + Trait Defaults | Fixed 2 pre-existing QSpec failures (missing imports), trait default method inheritance | | 10 | Parser Block Expressions + Harvest | do..end + curly blocks as primary expressions, 35 tests activated (traits, concurrency, generics) | | 11 | Task Group + Generics + Constant Dedup | task_group end-to-end (2 codegen fixes), recv_timeout, 13 generic tests, MIR constant dedup — 33 tests activated | | 12 | Generics Completion + Parser Fixes | 8 tracks: Option/Result predicates, bitwise newlines, curly blocks, type alias init, polymorphic dispatch, HashMap literals, Vec/HashMap type safety, as_type<T> — 36 tests activated | | 13 | Parallel Test Activation | Stream A (29 tests: F32 fixes, assert codegen, TYPE_NEVER) + Stream B (13 tests: multi-file, compile-error, generics/traits) — 39 tests activated | | 14 | Parallel Streams A+B | Stream A (30 tests: ptr_alloc, @heap, imports, closures, const eval) + Stream B (7 tests: HashMap keys, drop SSA, type alias dispatch) — 37 tests activated, 161 pending | | 15 | Parallel Streams A+B | Stream A (17 tests: compile-errors, defer fix, lambda arity, super-traits) + Stream B (24 tests: slices, field_offset, where clause, arenas) — 41 tests activated, 120 pending | | 16 | Regex String API | POSIX regex pattern tests (17) + PCRE2 regex tests (23: find_all, split, capture, matches) — 40 tests activated, 80 pending | | 17 | Regex Root Cause Fix | Fixed NODE_REGEX_LIT MIR bug + lexer pattern extraction — ~r literals, =~, !~, =~? all working — 17 tests activated, 63 pending | | 18 | User Macro System | Quote/unquote expansion, macro registry, parser (macro/quote/unquote keywords), clone_with_unquote AST cloning — 22 tests activated, 41 pending | | A+ | Arena Safety Analysis | Arena safety compile-error warnings, typecheck analysis pass — 4 arena tests activated, 37 pending | | QSpec | QSpec Infrastructure | Module init synthesis, intrinsic catchall fix, BE naming purge, capture_output intrinsics | | QM | QSpec Migration | COMPLETE — RSpec fully eliminated (223→0 .rb files). 21 new QSpec ports migrated to new API format with """ triple-quoted strings. Ruby dependency zero. std/shell.qz added. 319/319 files ALL GREEN, 49 it_pending (12 subprocess-related, 18 unimplemented features, 9 network tests, 4 type model, 4 platform limits, 2 other) | | MOD | Module Import Fix | Cross-module generic enums, parser arm boundary detection, tc_parse_type dot-to-dollar, resolver error handling | | 19 | Feature Completion Tier 1 | Mutable borrows, lambda type validation, safe navigation ?., modules/imports, record type intersection — 14 tests activated | | 20 | Deep Fixes | Traits resolver path, generic ptype creation, record returns — 6 tests activated | | 21 | Cross-Module UFCS Fix | Critical UFCS slot bug in resolver (NK_LET/NK_ASSIGN/NK_INDEX_ASSIGN/NK_FIELD_ASSIGN), cross-module generic enum return, global vars — 3 tests activated | | 22 | Finish Line + Phase U 8F | Worktree A: slice range arg swap, packed struct codegen, @cfg+@repr(C), regex match arms — 4 tests activated. Worktree B: intersection infrastructure (record storage, merging, width subtyping) + infer.qz TYPE_RECORD fix. ~14→~10 pending | | X.1 | Constant Deduplication | 3 phases: NODE_* (164 dups removed, ~440 refs → node_constants$), OP_* (30 dups removed, ~100 refs → op_constants$), TYPE_* (new shared/type_constants.qz, 55 constants + PTYPE_BASE). 14 files changed, net -439 lines. Fixpoint: 1357 functions | | X.2 | Compiler File Decomposition | 8 new module files: codegen split into 4 (codegen_util, codegen_intrinsics, codegen_runtime + core), typecheck split into 4 (typecheck_util, typecheck_builtins, typecheck_registry + core), mir split into 3 (mir_intrinsics, mir_const + core). Fixpoint: 1261 functions | | W1 | Parallel Wave 1 | Drop fix (match arm double-drop → emit_and_pop_drops_for_scope), VS Code extension (grammar, snippets, format-on-save), 12 example programs, generic type param fixes (TYPE_UNKNOWN→skip lambda check, TYPE_INT fallback). QSpec: 199/199, fixpoint: 1262 functions | | D | Error Recovery & Diagnostics | Parser multi-error recovery (ps_synchronize wired, 14 sync tokens, error limit 20), contextual help (notes vector, var/borrow/linear help), cascade prevention (tc_error limit 30, line+col dedup), fuzzy matching (prefix match, tc_suggest_type), --explain (10 error codes documented), JSON output (--error-format=json). New file: explain.qz. QSpec: 200/200, fixpoint: 1288 functions | | BC | Borrow Checker Completion | QZ1209 (mutation-while-borrowed, 5 assignment paths), QZ1210 (return borrow of local), QZ1211 (store borrow in struct field), ephemeral shared borrow release, borrow release on reassignment. 2 helper functions, 13 new tests. New doc: docs/BORROWING.md. QSpec: 200/200, fixpoint: 1291 functions | | MS | Move Semantics | Destructive moves for Drop types: 9 phases (type classification, Copy trait, assignment/call/return/conditional/match moves, MIR drop integration, error messages). 3 new error codes (QZ1212 use-after-move, QZ1214 inconsistent branch moves, QZ1215 Copy+Drop conflict). 6 module-level globals, ~16 new functions, MIR droppable stack transfer/consume. 30 new tests. QSpec: 201/201, fixpoint: 1307 functions | | M | Memory Model V2 | Design study (docs/design/MEMORY_MODEL_V2.md), width-aware Vec storage (Vec<U8> 1-byte elements), @value struct stack allocation, narrow struct fields, bounds-check elision (MIR_VEC_DATA_PTR/INDEX_RAW/INDEX_STORE_RAW), selective monomorphization, elem_width.qz shared module. 82+ tests across 3 spec files. Sieve benchmark updated to Vec | | F | Feature Gaps & Type System Polish | Fn type registry (ptype for Fn(A,B):C), Task return type fix, generic extend blocks (strip <T> from mangled name), Fn-in-struct-field calls (obj.f(args) via dot syntax), MAX_LOCALS bump. QSpec: 206/206, fixpoint: 1326 functions | | DG | Style Guide Overhaul + Codebase Dogfooding | 6 waves of mechanical modernization across 18 files (-143 lines net): compound assignment (x += 1), negative sentinels (-1), while→for-in loops, string interpolation (#{}), UFCS consistency (.push/.size/[i]), endless def. C bootstrap format.c fix for endless def preservation. QSpec: 206/206, fixpoint: 1326 functions | | TH | Type Hygiene | 5 tiers: struct field annotations (T1), func param Vec/HashMap annotations + nested generics (T2), eliminate as_int()/as_string() (T3), generic type params on vec_new/hashmap_new (T4), newtypes for compiler handles (T5): 199 param annotations across 11 files — 119 AstNodeId, 49 TypeId, 23 MirReg, 8 MirLabel. C bootstrap >> token splitting for Vec<Vec<Int>>. Gen1 fixpoint: 1357 functions. | | DG2 | Ergonomics Sprint Part 2 | QSpec ctx elimination (3,632 refs removed, 212 files), codegen_intrinsics interpolation (20 calls), spec modernization (39 str_from_int→interpolation), ufcs_complete_spec (17 new tests). QSpec: 208/209, fixpoint: 1325 functions. | | BF | to_str() Bugfix | Fixed SIGSEGV in string interpolation of negative integers: to_str() runtime used icmp ugt (unsigned), negative ints misidentified as string pointers. Changed to icmp sgt (signed). | | X.1 | Constant Sync | Constant sync tool (tools/sync_constants.rb), 4 missing NODE_ constants added to typecheck_util.qz | | U 8F | Union/Record Activation | Fixed type ID range collisions (tc_is_newtype/tc_is_union_type overlapping). Record types return TYPE_RECORD_BASE+idx, intersections return merged record, union types verified end-to-end. cancel_token builtins registered. 5 new union tests. QSpec: 209/210, fixpoint: 1327 functions | | X.4 | Intrinsic Dispatch Refactor | Replaced 388-handler sequential if/else chain with two-level HashMap dispatch (O(1) category lookup + ~30 comparisons per category). 16 categories, automated via tools/refactor_intrinsics.rb. QSpec: 209/210, fixpoint: 1342 functions | | S2.P | Partial Move Tracking | Per-field move state infrastructure (QZ1216): 8 functions, 3 globals, NODE_IDENT integration, if/else snapshot/merge. 4 pending tests. QSpec: 210/211, fixpoint: 1349 functions | | S2.B | Multi-Level Borrow Chain | Borrow chain propagation (QZ1217): re-borrows protect all ancestors via tc_propagate_borrow_chain, chain-aware release. 5 pending tests. QSpec: 210/211, fixpoint: 1350 functions | | S2.L | Scope-Based Lifetime Inference | Borrow lifetime validation (QZ1218): depth check at creation, dangling-reference detection at scope exit. Combined with QZ1210/QZ1209. 5 pending tests. QSpec: 211/212, fixpoint: 1350 functions | | F.R | Phase F Reset | g.spawn() UFCS fix (parser keyword-as-method after ./?.), debug print cleanup, trait constraint enforcement RESOLVED (was not blocked — test expectation updated). QSpec: 212/213, fixpoint: 1350 functions | | X.3+X.4+S2.4 | God Object + Dispatch + Safety Tests | X.3: TypecheckState 64→17 fields (4 sub-structs: TcErrors/TcScope/TcSafety/TcRegistry), MirContext 34→27 (2 sub-structs: MirDropState/MirGenericState), 21 module globals absorbed. X.4: tc_expr 2,296→506 lines (7 handler extractions). S2.4: 14 safety test bodies written (8 pass, 6 await infrastructure wiring). C bootstrap chained field assignment bug discovered. QSpec: 210/214, fixpoint: 1364 functions | | X.5 | Fixpoint Restoration | Restored fixpoint after nested-generics regression. 4 bugs: (1) bare TYPE_UNKNOWN in typecheck_util.qz missed by constant dedup, (2-3) parser postfix >> not split to > for nested generics vec_new<Vec<Int>>(), (4) match exhaustiveness == (pointer equality) → .eq() (content equality). gen1==gen2 byte-identical: 627,436 lines IR. QSpec: 227/228 | | STD.6+7+U | Serialization + Error Types + Unification | 10 commits: STD.7 Error trait + 6 concrete error types + Result/Option helpers. JSON hardened (Result errors, Bool predicates, UFCS extend, unicode \uXXXX fix). TOML hardened (Result errors, Float variant, serializer, UFCS). CSV module (RFC 4180). Unified naming aliases on all collections. Higher-order methods (each/map/filter/reduce/find/any/all/count) on Stack/Queue/Deque/LinkedList/PriorityQueue/SortedMap. Bytes Bool fix. File I/O Result migration. Serializable trait. ~3,000 lines added, 12 new test files. QSpec: 236/237 | | U.9 | Intersection Type Completion | COMPLETE (14/14 core): canonical ordering, impossible detection, tc_type_meet, display names, mixed record+trait (U.9.7), conflict detection fix (U.9.14), return position (U.9.15), multi-trait bounds (U.9.10), 16 active tests. 3 items permanently deferred by design (narrowing, distributivity, vtable dispatch → future dyn Trait phase) | | CMF | Cross-Module Fixes | 4 interconnected bugs: str_split/str_chars ptype (TYPE_INT→Vec), chained .size on struct Vec fields (auto-fixed by ptype fix), cross-module UFCS dispatch (auto-fixed), module-level global reassignment (mir_find_global_name + NODE_LET handler). 14 regression tests. QSpec: 247/248, fixpoint: 1,428 functions | | E2B | E.2 Blocker Fixes | 5 blockers investigated, 3 fixed: B5 Option/Result UFCS methods (extend blocks in std/prelude.qz), B3 @derive/doc-comment collision (prefixed doc slot), B1 MIR intrinsic return type fallback (mir_intrinsic_return_type, 30+ builtins). B4 string interpolation + B2 Vec verified as non-issues. +8 net test improvement. QSpec: 246/248 | | DX.1 | World-Class Debugger | 7 phases (1-5.2 + 1.7). Phase 1: !dbg on all instructions + terminators + fn_entry + column info. Phase 1.7: 526 intrinsic call sites annotated (16 categories). Phase 2: @llvm.dbg.declare for params/locals, 4 DIBasicTypes, DILocalVariable. Phase 3: 31 DICompositeType for structs with DIDerivedType members + pointer wrappers. Phase 4: ~38 per-module DIFile nodes. Phase 5.1: DISubroutineType deduped by signature. Phase 5.2: Enum DWARF — simple enums DW_TAG_enumeration_type + DIEnumerator; payload enums DW_TAG_structure_type with tag+payload members; built-in Option/Result. 8 tests in enum_debug_spec.qz. 355,809 !dbg annotations in self-compilation IR. Key files: codegen.qz, codegen_util.qz, codegen_intrinsics.qz, mir.qz (6 enum_defs accessors), mir_lower.qz (enum_defs population). Deferred: Phase 5.3 (lldb formatters), 6 (separate compilation debug). QSpec: 364/368, fixpoint verified | | SAH | Safety Adversarial Hardening | S2.4 Lifetime Inference complete: ephemeral reference model enshrined, S2.4.1-8 done. Partial move wiring (QZ1216 field-level), newtype enforcement (Vec rejects bare Int). S24 Move Fixes: match arm move tracking (per-arm snapshot/restore/N-way merge, QZ1214 for inconsistent moves), NODE_FOR move detection, NODE_IF expression-position move tracking, borrow-of-partial-move check (QZ1216). 3 audit holes fixed, 12 documented. 16 new tests. QSpec: 253/255, 1,430 functions | | F.1 | Parser Completion | Investigated #{} in closures (no bug — already working since Sprint 4) and | disambiguation (lexer cleanly separates |/||/|>). 8 interpolation confirmation tests across all closure contexts (arrow lambdas, do..end, curly blocks, captured vars). 21 adversarial parser stress tests (deep nesting, 15-param functions, 20-arm match, error recovery). QSpec: 249/250 | | STR2 | Type System Checks | STR2-2: Unknown type annotations — emit errors for undeclared types in var declarations and struct fields (6 tests). STR2-1: Generic struct init fix — as_string() field name conversion + annotation existence check to distinguish ‘field not found’ from unresolvable type params in tc_check_struct_init_field_types (6 tests). QSpec: 252/254, fixpoint: 1,430 functions | | S2.5 | Safety Audit Hole Fixes | ALL 12/12 holes fixed: #6 NODE_ASSIGN re-init (CRITICAL), #7 struct init, #13 lambda capture, #3 try/catch, #9 enum payload, #14 spawn (covered by #13), #15 defer (already correct), #10 match subject (verified), #4 while-loop (verified), #8 return move (verified), #12 transitive borrow (verified), #5 list comp move tracking (already implemented in typecheck_walk.qz, confirmed with 2 tests). 18 tests in s25 specs | | STRESS | Adversarial Test Suite | 8 new stress spec files: generics, closures, type inference, pattern matching, memory, modules, error recovery, interop. 170 tests total (143 passing, 27 it_pending). 8 bug categories discovered. 3,204 lines added. Residuals: +20 tests activated (QZI 14, arenas 5, vec_get deep copy 1), 4 permanent platform blockers documented | | SPEC.3+4 | Formal Eval Semantics + Memory Model | EVAL_SEMANTICS.md: operational semantics for all expression/statement types. MEMORY_MODEL.md: ownership, move, borrow, NLL-lite, drop, partial move rules. Precision sufficient for independent implementation | | PCH | Parallel Compiler Hardening (8 tracks) | Track A: MIR consumed value drops — emit_and_pop_drops for loop body, break/continue; mir_consume_droppable on return. Track B: Trait hang fix — parser defensive advance in trait/struct/impl method loops when unexpected token encountered. Track C: Generic enum match — tc_bind_pattern_variables resolves generic variant payload types via enum_variant_field_annotations + ptype arg extraction. Track D: Non-function call detection — tc_expr_call checks scope-found bindings for callable types, emits “Cannot call: has type X, which is not callable”. Antigravity tracks: TCO over-aggressiveness fix, S2.5 safety hole closures, cancel token MIR+codegen, duplicate type detection. Dup type fix: Moved detection from tc_register_struct_def/tc_register_enum_def to AST-level Phase 0 in tc_program — eliminates false positives from Phase 4.0a + tc_program double-registration pattern. QSpec: 274/275 (+1 over baseline). Fixpoint: 1,448 functions (with —no-cache) | | AG | Antigravity Validation | +6 tests (3 partial-move, 3 newtype dogfood) activated in partial_moves_spec.qz + newtype_dogfood_spec.qz. stress_large_program_spec.qz — 530+ line program passes. 2 new examples: brainfuck.qz + json_parser.qz (iterative tokenizer; recursive parse_value with str_eq causes compiler hang — known monomorphization loop). | | X.4-d | Dispatch Extraction (mir + codegen) | mir_lower_expr 2,446→660 lines (73% reduction, 8 category handlers: call, binary, match, concurrency, collection, lambda, alloc, try). cg_emit_instr 960→285 lines (70% reduction, 4 category handlers: call_ops, binary, index_ops, memory_ops). Follows proven tc_expr extraction pattern. Fixpoint: 1,460 functions | | FP | C Bootstrap Retirement & Release Binary | C_BOOTSTRAP → QUARTZ_COMPILER in Rakefile + bin/bench. quartz-bootstrap benchmark target removed. rake build:release uses llc -O2 (codegen optimization only — clang -O2 -x ir miscompiles). rake quartz:fixpoint rewritten for gen0→gen1→gen2 self-hosted validation. macOS ARM64 codesign -s - integrated. QUARTZ_VERSION synced to 5.12.21-alpha. Optimized release binary: 1,460 functions, 2.6 MB | | P.5-LP | Length-Prefixed Strings | String memory layout changed to [i64 length][char data...][null], pointer at char data, length at ptr[-8]. 3 new runtime helpers (qz_alloc_str, qz_wrap_cstr, qz_str_get_len). 4 codegen files changed (~60 functions). argv/get_arg wrap C strings at FFI boundary. 27s → 8.4s self-compilation (3.2× speedup, 69% reduction). Fixpoint: requires two-stage bootstrap (gen0→gen1→gen2→gen3, gen2==gen3). QSpec: 276/276 | | X.8 | String == Content Comparison | Two-part fix: (1) Compiler source audit: 3 rounds, 20+ ==→.eq() bugs in 5 files (mir.qz, resolver.qz, typecheck.qz, typecheck_registry.qz, mir_const.qz), 66 .eq(...)==1 verbosity instances cleaned across 7 files. (2) Operator fix: ==/!= on strings now emits str_eq (memcmp-based content comparison). Extended mir_is_string_expr with user-defined function return type lookup, NODE_INDEX string container element detection, str_split/str_chars result tracking. Removed unsafe mir_infer_expr_type fallback (caused false positives during monomorphization). Fixed is_string_op == OP_SUB → is_string_op == 1. 35 adversarial tests in string_equality_spec.qz (13 categories). QSpec: 277/277, build: 1,462 functions | | STRESS-S | Stress Test Stabilization | Heredoc \# escape fix in lexer (backslash skips next char in heredoc scanner, prevents \#{} triggering interpolation). 5 new stress files stabilized: string_ops (34/34), concurrency (15/15), collections (22+3 pending), safety_combined (16+3 pending), macros (8+10 pending). 16 pre-existing limitations identified and tracked as action items (7 distinct root causes). Fixpoint: 1,466 functions. QSpec: 278/279 | | NET | Networking & TLS Stdlib | Complete networking standard library: TCP client/server (std/net/tcp.qz), TLS/HTTPS with OpenSSL 3.x (std/ffi/tls.qz, std/net/tls.qz), HTTP client with redirect following (std/net/http.qz), HTTP server with routing + CORS (std/net/http_server.qz), buffered I/O (std/net/buffered_net.qz), timeouts (time_epoch_ms via gettimeofday). 6 key bugs fixed (send/recv intrinsic collision, CInt sign-extension, string == pointer comparison, cross-module struct field index, htons double-swap, P.5 string boundary). 41 active tests across 5 spec files, 14 pending. 15 files changed, +3,278 lines | | P.2 | Incremental Compilation (Tier 0 + Tier 1) | Tier 0: Pre-resolution quick-check — hash all source files, return cached IR if unchanged (9s → 23ms, 400× speedup). Tier 1: Per-module codegen caching with dependency graph (dep_graph.qz), BFS invalidation with interface hash early cutoff, string pool dedup + pre-loading, deterministic metadata slots, per-module IR fragment save/load. Key bugs: cross-test cache contamination (QSpec --no-cache), same-program safety check, missing fragment pre-scan. 10 dep_graph tests. 7 files changed. QSpec: 280/297 (17 failures from newly added test files). Build: 1,521 functions | | F.2-VG | Vec<Struct> Generics Fix | Root cause: tc_make_ptype(TYPE_VEC, TYPE_STRUCT, 0) collapsed different struct Vec types to same ptype. Fix: use struct registry index as arg2. Added tc_ptype_name/tc_ptype_set_name for struct name propagation through vec_get/vec_pop/index. 11 tests in vec_struct_generics_spec.qz. 3 files changed (typecheck.qz, typecheck_util.qz, typecheck_walk.qz) | | OH | Overnight Hardening | 3 bugs fixed, 2 design docs: (1) Iterative capture walker — replaced recursive mir_collect_captures_walk with worklist-based iterative version (mir.qz, 3 helpers). Root cause: 8MB stack overflow on closure-heavy files. Critical: Vec<Int> params typed as Int caused silent vec_push failure. (2) Parser multiline string hang — confirmed as SIGSEGV manifestation, not parser bug. (3) Tier 2 incremental correctness — depgraph_invalidate_with_cutoff now always propagates from seed modules (MIR inlines bodies cross-module). 2 incr_tier2_spec it_pending activated (7/7 pass). dep_graph_spec updated (9/9 pass). Design docs: SEPARATE_COMPILATION.md, C_BACKEND.md. QSpec: 319/319, fixpoint verified | | AG2 | Anti-Gravity Session (8 Parallel Features) | 8 features developed in parallel worktrees, merged to trunk: (1) Did You Mean — Levenshtein distance suggestions for undefined identifiers in typecheck_registry.qz; 3 new tests, 2 it_pending activated. (2) SIMD Convert — simd_convert_f32x4_to_i32x4/simd_convert_i32x4_to_f32x4 spec tests activated (2 tests). (3) SIMD Gather/Scatter — spec tests for llvm.masked.gather/llvm.masked.scatter (2 it_pending — needs vec_new_f32 replacement). (4) x86_64 Cross-Compilation — spec test for x86_64 target triple (1 it_pending — triple not emitted yet). (5) WASI Declaration Gating — cg_is_wasi() helper gates POSIX declarations, @_start entry for WASI; 3 it_pending activated + 4 new tests (7 total). Fixpoint ✓. (6) Freestanding Allocator Gating — @malloc/@free omission spec activated (1 it_pending activated + 6 new tests). (7) extern var — NODE_EXTERN_VAR (kind 76), parser/resolver/codegen for extern var name: Type → @name = external global i64. 6 files changed. Fixpoint ✓. (8) Struct-Heavy Benchmark — Point3D + BoundingBox benchmark (100K points × 50 iterations, Quartz vs C). 9 it_pending resolved (49→40). QSpec: 319/319, fixpoint: 1,533 functions | | LEO-W | Worktree Dogfooding (W.1-W.6) | W.1: 6 documentation errors fixed (07bb3c6). W.2: .eq() → == (169 occurrences, fb71582). W.3: .concat() → #{} interpolation (273 changes, 21 files, 4d95260). W.4: 0 - 1 → -1 (97 instances, fb71582). W.5: SKIPPED — for loop counter is immutable by design. W.6: Magic ASCII → char literals (359 changes, 23 files, 4d95260). W.7: SKIPPED — Drop for builtin types infeasible. 44 files changed, 632 insertions/632 deletions in W.3+W.6 alone | | LEO-6 | Phase 6: Operator Traits | Unified trait/operator dispatch: Eq/Ord methods renamed to op_* names (eq→op_eq, lt→op_lt, etc.). 6 new arithmetic/index traits (Add, Sub, Mul, Div, Mod, Index). @derive(Eq) now enables == operator. @derive(Ord) enables < operator. Comparison operators return TYPE_BOOL. op_index fallback dispatch for struct[key]. NODE_BINARY struct_name propagation (c = a + b preserves struct type for downstream == dispatch). 12 tests in operator_traits_spec.qz. 5 existing spec files updated. QSpec: 325/325, fixpoint: 1,577 functions | | LEO-7 | Phase 7: Iterator Protocol | Formal Iterator<T> trait, closure-based lazy adapters (Map/Filter/Take/Skip/TakeWhile), 10 terminal ops, VecIter/RangeIter, for-in integration, field-assign offset bug fix. 38 tests in iterator_protocol_spec.qz | | LEO-7.5 | Phase 7.5: Generic UFCS Dispatch | Closure-based dispatch for <T: Iterator> bounded generics. PASS 0.9.1 tags Iterator-bounded entries. synthesize_next_closure auto-generates -> arg.next() lambdas. lower_closure_iteration for for-in on Iterator params. 8 tests in generic_ufcs_dispatch_spec.qz | | LFA-A | Bool Hygiene (A.1-A.6) | A.1-A.4: ~450 replacements across 20 compiler files. A.5: ~266 replacements across ~50 std/tools/spec files (json, argparse, lexer, parser, matchers, subprocess, iter, string, quake, collections, io, net + 30 spec files). A.6: check_bool_hygiene() lint rule in tools/lint.qz — Tier 1 (== true/false, != true/false) + Tier 2 (known predicates + == 1/0 with allowlist). 14 tests in lint_bool_hygiene_spec.qz. Key: not on closure calls fails (typechecker limitation), $assert uses not internally. QSpec: 327/332, fixpoint verified | | LFA-F | Documentation Accuracy Audit (F.1-F.4) | F.1: QUARTZ_REFERENCE.md — v5.26 header, removed stale C bootstrap refs, fixed macro docs, corrected str_find/vec_pop signatures, added 4 new sections (Impl Blocks, Tuples, Iterators, v5.26 Breaking Changes), updated stdlib table. F.2: ARCHITECTURE.md — updated function count (~3,261), line count (~70,445), QSpec file count (332). F.3: 131-line Collections section in QUARTZ_REFERENCE.md (all 6 collections). F.4: INTRINSICS.md complete overhaul (~40 → ~250+ builtins, 25+ categories). QSpec: 323/334, fixpoint verified | | LFA-D6 | Collection Iterator Integration (D.6) | .iter() on all 6 collections: StackIter (bottom-to-top), QueueIter (front-to-back with head offset), DequeIter (snapshot approach — ring buffer math broke on 5-field structs), LinkedListIter (_next chain), PQIter (array order), SortedMapKeyIter + SortedMapValueIter (sorted iteration). 15 tests in collection_iterators_spec.qz. Bugs found: .size on Vec<Int> fails cross-module, structs with 5+ fields have layout issues in iterator contexts. QSpec: 323/334 | | LFA-B | Option Match Migration (B.0-B.2) | B.0: Confirmed cross-module Option matching works (not blocked as originally assessed). B.1: std/iter.qz — 18 sites migrated to match destructuring; requires _ => wildcard in every Option match. 38/38 iterator tests pass. B.2: std/string.qz + std/net/http.qz + std/net/http_server.qz — ~30 sites migrated. ~48 option_is_some/option_get anti-patterns eliminated total. QSpec: 326/334, 0 new regressions | | LFA-C | UFCS Type Inference Fix + .size Re-application | 4 changes in typecheck_walk.qz: (1) NODE_LET ptype annotation population — reconstructs type_ann from ptype when init_type >= PTYPE_BASE. (2) NODE_GLOBAL_VAR ptype annotation — same logic + tc_scope_bind_full with type_ann. (3) .size annotation fallback — when object_type == TYPE_INT and object is NODE_IDENT, recovers container type from binding’s type_ann (Vec/String/HashMap/Set/StringBuilder). (4) UFCS method dispatch fallback — same fallback for first_arg_type == TYPE_INT. Safety fix: tc_resolve_expr_struct_name filters builtin container type names (Vec, HashMap, Set, Option, Result, String, etc.) to prevent “Unknown struct: Vec” errors when annotation contains ptype like “Vec”. 14 .size re-applied across 6 files (csv, json, json/stringify, toml/stringify, toml/value, toml_spec). 8 diagnostic tests in ufcs_inference_spec.qz. QSpec: 323/334, fixpoint verified | | LEO-8 | Phase 8: Option<T> Returns | In-place migration of fallible builtins from sentinels to Option<T>: str_find → Option<Int>, hashmap_get → Option<T>, vec_pop → Option<T>, vec_index_of/regex_match_start/regex_match_end → Option<Int>. New str_contains intrinsic. Codegen helpers for Option construction. Two-stage bootstrap: eliminated compiler self-dependency on changed functions, then changed codegen. ~80 call sites migrated across compiler + stdlib. QSpec: 327/328, fixpoint: 1,588 functions | | LEO-9a | Phase 9a: First-Class Tuples | (expr, expr) construction, .0/.1 typed element access, (T1, T2) type annotations. NODE_TUPLE_LITERAL (kind=77), TYPE_TUPLE (53), g_tuple_elem_types registry. Parser, typecheck, MIR lowering, all auxiliary passes. 10 tests in tuple_spec.qz. Fixpoint verified | | LEO-9b | Phase 9b: Tuple Destructuring | var (a, b) = expr via NODE_LET_DESTRUCTURE (kind=78). Parser detects var ( pattern, typecheck validates arity + binds element types, MIR lowers to temp + load_offset per binding. Capture walker, liveness, resolver handlers. 10 tests in destructuring_spec.qz. QSpec: 326/331, fixpoint: 1,600 functions | | LEO-9c | Phase 9c: Struct & Vec Destructuring | Full-stack implementation: Point { x, y } = expr (type name required at statement level), var { x, y } = expr (type inferred), var Point { x, y } = expr (mutable), Point { x: px } = expr (field renaming), Point3D { x, .. } = expr (partial with rest). Vec: [a, b] = vec, [head, ..rest] = vec (rest creates new vec via loop), [head, ..] = vec (head only). Match patterns: match val; Point { x, y } => ...; end. For-in patterns: for Point { x, y } in items. NODE_STRUCT_DESTRUCTURE (kind=79) + NODE_VEC_DESTRUCTURE (kind=80), int_val=-1 for pattern context. Parser: ps_parse_struct_destr_fields + ps_parse_vec_destr_elems helpers, integrated into ps_parse_let, ps_parse_stmt, ps_parse_pattern, ps_parse_for_labeled. TC: struct type validation via tc_find_struct_def, field resolution, Vec rest binding with Vec<Int> ptype for UFCS .size support. MIR: mir_emit_load_offset with resolved field index (not mir_emit_field_access which produced garbage operands). 881 lines across 9 files + 1 new test file. 12 tests in struct_destructure_spec.qz. QSpec: 302/340, fixpoint verified | | LF2.1 | Or-Patterns in Match Arms | pat1 \| pat2 \| pat3 => body. NODE_OR_PATTERN (kind=81) in node_constants.qz. ast_or_pattern constructor. Parser: \| between patterns in ps_parse_match_arm + arm boundary detection fix (IDENT followed by \| now recognized as new arm start). TC: sub-pattern validation (rejects struct/vec destructuring in or-patterns), exhaustiveness coverage (or-patterns count toward enum variant coverage). MIR: comparison chain lowering — each sub-pattern creates test block branching to arm_block on match or falling through to next test; handles NODE_WILDCARD, NODE_ENUM_ACCESS, NODE_IDENT, NODE_STRING_LIT, literals. Both mir_lower_match_expr and mir_lower_stmt_match. Pass-throughs: macro_expand clone, liveness walk, capture walker. Supports: integers, strings, bools, qualified/unqualified enum variants, guards, expression position, nested match, mixed arm types, return in arm. 33 tests in or_pattern_spec.qz. 11 files changed. QSpec: 333/340, fixpoint verified | | LF2.6 | Spread Operator | [...a, ...b] — Collection spreading in array literals. NODE_SPREAD (kind=82) in node_constants.qz. ast_spread constructor wraps inner expression in left field. Parser: ...expr prefix detection in array literal context (after [ and after ,); parse error when combined with list comprehension. TC: for-loop over elements unwraps NODE_SPREAD to walk inner; tc_infer_expr_type_annotation returns inner vec’s type directly. MIR: mir_lower_array_with_spread — dynamic vec_new() + per-element vec_push for plain elements, vec_len/vec_get loop for spread elements (reuses existing intrinsics, no codegen changes). Both stack-alloc and heap/arena alloc paths detect spread and redirect. 7 walker sites: TC capture, MIR iterative capture, liveness, macro expand (expand_node + clone_with_unquote), resolver (UFCS transform + rewrite). AST debug print. 10 files changed, 1 new test file. 15 tests in spread_operator_spec.qz. QSpec: 324/343, fixpoint verified | | LEO-10 | Phase 10: stdlib Additions | 10.1: vec_clone intrinsic (shallow memcpy), is_upper/is_lower character intrinsics, 32-byte Vec header migration (array literals + 5 runtime functions now store elem_width at header[3]). 10.2: iter_enumerate/iter_zip tuple-yielding adapters in std/iter.qz. 10.3: New std/vec.qz — vec_first, vec_last, vec_map, vec_filter. QSpec: 326/331, fixpoint: 1,600 functions |

Integration Test Failures

Status (Feb 24, 2026): 3,274 examples, 2 pre-existing failures (slices range syntax, TOML escape sequences — both pre-existing, unrelated to recent work). All 52 originally tracked failures fixed.

All previously failing categories now pass:

Map comprehensions (10) — codegen crash fixed
Visibility / priv (4) — struct/enum enforcement added
Variadic extern (4) — LLVM function type emission fixed
Operator overloading (4) — extend-based dispatch fixed
Extend blocks (3) — method dispatch fixed
Const eval (2) — loop evaluation fixed
@x field sigil (2) — field rewriting fixed
Slices (1) — range syntax working
Regex (1) — named capture groups working
Traits (1) — generic impl working
JSON (21) — cross-module suffix search (Case 4b)
TOML parser (17) — cross-module suffix search + duplicate TomlLocation removal
Event loop (8) — cross-module suffix search
Argparse (6) — cross-module suffix search (NOT arity mangling as previously thought)

QSpec: 338 files (25 pre-existing failures). 12 it_pending (6 PERMANENT, 6 DEFERRED) across 8 files — categorized:

~~Subprocess-related (12)~~: 11 ACTIVATED — ffi_spec (5), networking_spec (4), variadic_extern_spec (2) all tests active. tls_spec (1) remains it_pending (DEFERRED — needs local TLS server with test certificate)
~~Unimplemented features (11)~~: ALL IMPLEMENTED — c_backend_spec (6 — --backend c with new codegen_c.qz), simd_gather_scatter_spec (2 — vector API with @llvm.masked.gather/scatter intrinsics), cimport_spec (2 — cimport "header.h" keyword + std/ffi/ stub files), cross_compilation_spec (1 — x86_64-unknown-linux-gnu triple)
~~Network tests pending (9)~~: RESOLVED — SIGSEGV fixed by iterative capture walker. 4 converted to HTTP response parsing tests (pure functions), 5 DEFERRED (require local TCP server infrastructure)
PERMANENT type model limitations (2): type_errors_spec (1 — PERMANENT: existential type model erases String/Int distinction), stack_trace_spec (1 — PERMANENT: same)
PERMANENT platform/runtime limits (4): regex_advanced_spec (2 — PERMANENT: POSIX ERE lacks non-capturing groups/backreferences), fixed_width_integers_spec (1 — PERMANENT: htons() is C macro, not resolvable by lli JIT), vec_string_spec (1 — PERMANENT: PCRE2 runtime not linked in lli interpreter) ~3,000+ active tests.

Notable bug: ~~SIGSEGV with closure-heavy imports~~ RESOLVED — two root causes: (1) C bootstrap MAX_LOCALS overflow (retired Feb 2026). (2) Recursive mir_collect_captures_walk stack overflow on deeply nested closure-heavy files — fixed Mar 2026 with iterative worklist walker (3 helper functions, explicit scope chain). Critical discovery: Vec<Int> helper functions typed as Int caused vec_push to silently fail (element width unknown).

Phase F: Feature Gaps & Type System Polish (Feb 24, 2026)

Goal: Close remaining feature gaps in generics, function types, and concurrency type tracking.

Phase	Description	Tests	Status
F-Alpha	Triage & verify non-issues (`#{}` closures, `	` disambiguation, HashMap generics)	0
F-Beta	Fn type registry (ptype for `Fn(A,B):C`) + Task return type fix	+10	DONE
F-Gamma	Generic extend blocks (strip `<T>` from mangled name)	+5	DONE
F-Delta	Fn-in-struct-field calls (`obj.f(args)` via dot syntax)	+6	DONE

Key changes:

Fn type registry: tc_parse_type creates ptypes for Fn(...) instead of bare TYPE_FUNCTION. Registry stores param count and return type per Fn signature. tc_type_is_function() helper checks both bare and ptype forms.
Task fix: NODE_SPAWN uses g_last_lambda_body_type instead of hardcoded TYPE_INT.
Generic extends: resolver.qz strips <T> from mangled name (GBox<T>$get → GBox$get), keeps full annotation for self_type field access.
Fn-field calls: Typechecker detects Fn-typed struct field matching UFCS func_name, rewrites callee to FIELD_ACCESS, returns immediately. FIELD_ACCESS callee handler at top of NODE_CALL handles re-entry. MIR emits indirect call via mir_emit_call_indirect.
MAX_LOCALS: C bootstrap mir_codegen.c bumped 512→640 (Fn type globals exceeded limit).

Deferred: ~~multi-level closure capture~~ (FIXED — mir_ctx_bind_var), regex (PCRE2). Cancel_token builtins now registered (Phase U 8F). g.spawn() UFCS fixed in Phase F Reset.

@derive macros: COMPLETE. @derive(Eq, Hash, Show, Clone, Ord) on structs generates impl blocks at Phase 2.4 (after parsing, before macro expansion). Source string generation + re-parse approach. Typed params with dot-syntax field access. 15 tests in derive_spec.qz. Files: derive.qz (new), parser.qz (annotation parsing), macro_expand.qz (NODE_STRUCT_INIT cloning), quartz.qz (pipeline integration).

Resolved: Trait constraint enforcement (Wave 1) — tc_validate_trait_bounds works correctly. The “resolver bug” was a stale observation; tc_program sees all children. Test expectation updated from monomorphizer fallback (“Undefined function”) to proper constraint error (“does not implement trait”).

Fixpoint: 1357 functions (up from 1307).

Phase TH: Type Hygiene — Proper Type Annotations for Self-Hosted Compiler

Goal: Eliminate bare Int as an opaque handle type throughout the self-hosted compiler. The compiler that enforces types should use types. Every variable that holds a Vec<T>, HashMap<K,V>, or domain-specific handle should be annotated with its true type. This enables UFCS, provides compile-time safety, and makes the compiler the definitive example of idiomatic Quartz.

Discovery: Phase DG UFCS wave found ~40% of potential conversions blocked because variables are typed as Int (opaque handles) rather than Vec<T> or HashMap<K,V>. The C bootstrap can’t resolve UFCS methods on Int-typed variables.

Prime Directive: Every change must preserve fixpoint. Annotations are purely compile-time — same LLVM IR, same binary. Fixpoint should hold by definition, but validate after every tier.

Tier Status

Tier	Description	Status
T1	Struct field annotations (TypecheckState, MirContext)	DONE — 7 fields annotated
T2	Function param Vec/HashMap annotations	DONE — all 12 VoV fields typed (`Vec<Vec<Int>>` + `Vec<Vec<String>>`), C bootstrap `>>` token splitting enables `vec_new<Vec<T>>()`, 4 registration params annotated.
T3	Eliminate as_int()/as_string() pattern	DONE — ~51 calls eliminated + 7 additional VoV handle casts removed (5 `as_string()` on reads, 2 `as_int()` on stores).
T4	Generic type params on vec_new()/hashmap_new()	DONE — ~150 calls annotated across 15 files
T5	Newtype param annotations (AstNodeId/TypeId/MirReg/MirLabel)	DONE — 199 annotations across 11 files, 3 waves

Tier 5: Mass Newtype Dogfooding (Feb 24, 2026)

199 param annotations across 11 files, organized in 3 waves:

Wave	Newtype	Params	Files
1	AstNodeId	119	ast.qz(51), macro_expand.qz(8), parser.qz(2), resolver.qz(10), typecheck.qz(20), mir.qz(24), mir_const.qz(4)
2	TypeId	49	typecheck.qz(39), typecheck_registry.qz(9), typecheck_builtins.qz(1)
3	MirReg + MirLabel	31	mir.qz(29), codegen_util.qz(2)

Skipped params (C bootstrap limitations):

Params pushed into Vec<Int>() — 5 functions (mir_body_has_ufcs_calls, mir_try_op_overload, mir_emit_index_store_raw val, tc_make_ptype, tc_register_function)
UFCS .to_s() on newtype — cg_format_operand (C bootstrap can’t dispatch UFCS on newtype)
Polymorphic accessor — mir_block_set_terminator data (sometimes MirLabel, sometimes MirReg, sometimes literal)
Array literal storage — mir_ctx_push_loop break_block/continue_block

Not in scope (deferred to Phase ASR):

Return types — polymorphic accessors (ast_get_left, mir_instr_get_operand1) prevent this
Constructor return types — would require annotating all callers that store the result
Vec element types — Vec<MirReg>, Vec<AstNodeId> etc. (requires Vec-of-newtype support)
ScopeId / DiagId — lower priority newtypes not yet defined

Verification: Build PASS, Gen1 fixpoint 1357 functions (annotations are transparent).

Tier 1: Struct Field Annotations

Scope: TypecheckState (~55 Int fields), MirState, ParserState, and other core structs.

What: Change struct fields from bare Int to their true types (Vec<Int>, Vec<String>, HashMap<String, Int>, etc.).

Why first: Struct fields are the root cause — every access to tc.builtins flows through the struct definition. Fix the struct, and all downstream accesses inherit the correct type.

Key structs to annotate:

TypecheckState in typecheck_util.qz — ~55 fields, majority are Vec<Int>, Vec<String>, HashMap<String, Int>
MirState in mir.qz — emission state, scope stacks, label counters
ParserState in parser.qz — token streams, error recovery vectors
AstStorage in ast.qz — node arenas (these may stay Vec<Int> since node IDs are genuinely Int indices)
EGraph/EClass/ENode in egraph.qz — optimization state

Constraints:

C bootstrap must handle typed struct fields. Verify with a small test struct first.
Some fields are genuinely Int (counts, indices, flags, type IDs) — don’t over-annotate.
~~Fields that store Vec<Vec<String>> via as_int() pattern will need Tier 3 first if nested generics don’t work.~~ RESOLVED: C bootstrap >> token splitting fix enables Vec<Vec<String>> fields; all handle casts eliminated.

Dogfooding: After annotating each struct, convert all field accesses to UFCS where newly enabled (.push(), .size, [i], .get(), .set(), .has()).

Verification: rake build && rake qspec (206/206) after each struct.

Tier 2: Function Parameter & Return Type Annotations

Scope: ~100+ functions across typecheck_registry.qz, mir.qz, codegen.qz, resolver.qz that accept Int params which are actually Vec<T> or HashMap<K,V>.

What: Change function signatures from def f(field_names: Int) to def f(field_names: Vec<String>).

Why after Tier 1: Once struct fields are typed, function params that receive struct field values should match. This is a consistency pass.

Key functions (examples):

tc_register_struct(tc, name, field_names: Int, field_types: Int, ...) → field_names: Vec<String>, field_types: Vec<Int>
tc_register_enum(tc, name, variant_names: Int, variant_payloads: Int, ...) → variant_names: Vec<String>, variant_payloads: Vec<Int>
mir_emit_* functions that accept AST store/node handles
codegen_emit_* functions with similar patterns

Constraints:

Must update all call sites to match (types are checked at compile time).
Some functions genuinely accept opaque Int (type IDs, node indices) — don’t change those.
C bootstrap must handle typed parameters in all positions.

Dogfooding: Convert function bodies to UFCS where newly enabled by the typed params.

Verification: rake build && rake qspec (206/206) after each file.

Tier 3: Eliminate `as_int()/as_string()` Pattern

Scope: ~284 as_int()/as_string() calls across 17 files.

What: Replace Vec<Int> storing as_int(string_value) with Vec<String> storing strings directly. Eliminate the manual type-erasure pattern.

Why after Tier 2: Struct fields and function params must already be typed correctly before we can change the element types of their collections.

Key patterns to eliminate:

var names = vec_new<Int>() + names.push(as_int("hello")) → var names = vec_new<String>() + names.push("hello")
as_string(names[i]) → names[i]
TypecheckState registry fields that store Vec<Int> of as_int(String) → Vec<String>

Risk: MEDIUM — this changes the actual data flow, not just annotations. If Vec<String> and Vec<Int> have different runtime behavior for any reason, this breaks. Test thoroughly.

Constraints:

Verify Vec<String> push/get/index works identically to Vec<Int> with as_int() values (should be identical since String IS Int at runtime).
Some as_int() uses are for non-string types (storing Vec handles in Vec). Those need Vec<Vec<T>> or stay as-is with a comment.
as_int()/as_string() for Vec/HashMap handles stored in Vec may need nested generic support. If not available, document and defer that subset.

Dogfooding: After eliminating as_int()/as_string(), the code becomes dramatically more readable. No more as_string(field_names[i]) — just field_names[i].

Verification: rake build && rake qspec (206/206) after each file. Extra careful — this changes data flow.

Tier 4: Local Variable Annotations

Scope: ~200+ local variables typed as Int via inference where the inferred type is too weak.

What: Add explicit type annotations to local variables where inference produces Int but the semantic type is Vec<T>, HashMap<K,V>, or another container.

Why last among annotation tiers: Once structs, params, and as_int() are fixed, many locals will already infer the correct type from context. This tier catches the remaining ones.

Key patterns:

var fields = ast_get_children(store, node) — returns Int, should be Vec<Int> (but ast_get_children may return Int by design as an arena handle)
var result = vec_new() — infers Int, should be var result: Vec<String> = vec_new() or var result = vec_new<String>()
var scope = hashmap_new() — should be var scope: HashMap<String, Int> = hashmap_new()

Constraints:

Don’t annotate variables that are genuinely Int (loop counters, flags, node indices, type IDs).
Prefer generic parameter syntax (vec_new<String>()) over annotation syntax (var x: Vec<String> = vec_new()) where possible — it’s more concise.

Dogfooding: Convert all newly-typed locals to UFCS.

Verification: rake build && rake qspec (206/206).

Tier 5: Newtypes for Semantic Distinction

Scope: Language feature addition + compiler dogfooding.

What: Add a type keyword for newtype declarations that create distinct types wrapping an underlying type. Then use them in the compiler for AstNodeId, TypeId, MirReg, etc.

Syntax:

type AstNodeId = Int     # Distinct from Int — cannot be used interchangeably
type TypeId = Int        # Same runtime repr, different compile-time identity
type MirReg = Int        # Prevents passing a TypeId where a MirReg is expected

Why a language feature: Without newtypes, AstNodeId and TypeId are both Int and can be silently mixed. The type system should catch tc_lookup_struct(tc, ast_node) where ast_node: AstNodeId but tc_lookup_struct expects TypeId.

Implementation order (bootstrap-first):

C bootstrap: Add type Name = Underlying parsing (NODE_TYPE_ALIAS already exists, extend for newtype semantics)
C bootstrap: Typechecker treats newtype as distinct — cannot assign Int to AstNodeId without explicit conversion
C bootstrap: Codegen erases newtype to underlying type (existential model preserved)
Verify: Build self-hosted compiler with C bootstrap
Self-hosted: Add same feature to Quartz compiler
Verify: Fixpoint
Dogfood: Apply newtypes to self-hosted compiler source

Newtypes to define:

type AstNodeId = Int — arena indices into AstStorage
type TypeId = Int — type system type identifiers (TYPE_INT, TYPE_STRING, etc.)
type MirReg = Int — MIR virtual register numbers
type ScopeId = Int — scope tracking indices
type DiagId = Int — diagnostic indices (if applicable)

Conversion functions: Each newtype needs to_int() and from_int() (or AstNodeId(n) constructor syntax) for interop boundaries.

Risk: MEDIUM-HIGH — this is a language feature change. Must be added to C bootstrap first. Must not break any existing code (existing type X = Y aliases should still work as aliases, newtypes are opt-in or use different syntax like newtype).

Dogfooding: After adding newtypes, convert all ~200+ AST handle variables, ~100+ type ID variables, and ~50+ MIR register variables to use the newtypes. This will catch bugs where different handle types are mixed.

Verification: rake build && rake qspec (206/206). Fixpoint must hold after each step.

Outcomes

Metric	Before	After T1-T4	After T5 (actual)
Bare `Int` for Vec/HashMap handles	~200	~0	~0
`as_int()/as_string()` calls	~284	~20 (non-string)	~20
UFCS-blocked conversions (from DG)	~200	~0	~0
Bare `Int` for AST/Type/MIR handles	~350	~350	~150 (199 annotated, ~150 remaining — return types, Vec elements, skipped polymorphic)
Compile-time type safety holes	~600	~370	~170

Completed Sprint Detail (Summary)

Full detail for all completed sprints and phases is preserved in ROADMAP-v5.25.0.md.

Sprint/Phase	Tests Activated	Key Achievement
Sprints 1-3, 6	32 RSpec fixes	All RSpec failures eliminated
Sprint 4: Parser Workarounds	+53	Match guards, `??`, `#{}` closures, hashmap literals
Sprint 5: API Unification	+4	vec_free, hashmap_free, sb_free codegen
Sprint 7: QSpec Activation	+57	47 property tests, pending audit complete
Sprint 8: Documentation	0	Roadmap, reference, API docs updated
Phase 1: Quick Wins	+20	Const eval, argparse, arity, visibility
Phase 2: Monomorphization	+19	Bounded generics, trait dispatch, type alias validation
Phase 3: Drop Codegen	+19	8 RAII tests, labeled loops, generic enums
Phase 4: Compile-Error Sweep	+15	TOML lexer helpers, error message tests
Phase 5: Multi-Module	+13	Drop scope fixes, trait signature verification
Phase 6: Concurrency	+16	Select, generic functions, set_members fix
Phase 7: F32 Fix	+16	F32 param marking, literal suffixes, drop tests
Structural Dispatch	+25	Zero-cost compile-time duck typing
Phase 8: Record/Structural	+7	Record types, structural properties
Phase 9: Trait Defaults	+8	Default method inheritance, QSpec fixes
Phase 10: Block Expressions	+35	do..end, curly blocks, trait harvest, concurrency
Phase 11: Task Groups	+33	Closure wrapper fix, generic struct returns, MIR dedup
Phase 12: Generics	+36	Option/Result predicates, HashMap literals, `as_type<T>`
Phase 13: Parallel A+B	+39	F32 return types, assert codegen, TYPE_NEVER
Phase 14: Parallel A+B	+37	ptr_alloc, @heap, imports, drop SSA fix
Phase 15: Parallel A+B	+41	Compile-errors, slices, where clauses, arenas
Phase 16-17: Regex	+57	POSIX regex, PCRE2, NODE_REGEX_LIT MIR fix
Phase 18: Macros	+22	Quote/unquote, macro registry, string templates
Arena Safety	+4	Compile-error warnings, typecheck analysis
Phases 19-22	+27	Mutable borrows, safe navigation, record intersection, packed structs
Parallel Tracks A-C	+17	Closure spawn, private visibility, diagnostic engine
Total	~650+	QSpec: 212/214, ~2,800+ active tests

Integration Test Status

3,274 RSpec examples, 2 pre-existing failures (slices range syntax, TOML escape sequences). All 52 originally tracked failures fixed.

QSpec: 212/214 files pass. ~2,800+ active tests, ~18 pending (14 safety infrastructure + 3 PCRE2 platform limits + 1 htons extern). Gen1 fixpoint: 1357 functions.

Completed Sprint/Phase Detail (click to expand — 22 phases, ~650 tests activated)

Sprint 1: Extend Blocks, Operator Overloading & @field Sigil — COMPLETE

All 9 RSpec failures already fixed. 19 tests pass.

Sprint 2: Map Comprehensions — COMPLETE

All 10 RSpec failures already fixed. Tests pass.

Sprint 3: Visibility, Variadic Extern, Const Eval — COMPLETE

All 10 RSpec failures already fixed. Tests pass.

Sprint 4: Parser Workaround Elimination — COMPLETE

Target: ~80 QSpec tests activated, ~5 property tests

Task	Description	Status
4.1	`#{}` string interpolation inside closures	DONE (was already working)
4.2	Fix hashmap literal `{}` inside closures — `{` disambiguation	DONE
4.3	Fix `??` nil coalescing operator — OP_MATCH/OP_NOMATCH renumbered	DONE
4.4	Match guards — parser binding, typechecker, MIR for all pattern types	DONE
4.5	Unqualified enum patterns — `Variant(x)` without `Type::` prefix	DONE

Activated: 53 tests across 7 spec files (string interpolation, boolean .empty?, match guards, nil coalescing, defer early-return, hashmap literals in closures).

Sprint 5: API Unification Completion — COMPLETE

Task	Description	Status
5.1	Register missing UFCS methods (`StringBuilder$size`, `String$cmp`)	DONE
5.2	Implement vec_free codegen handler	DONE
5.3	Update UNIFIED_API.md to match reality — 40+ methods documented	DONE
5.4	Add property tests for collection operations	DONE (7 tests in hashmaps + collection_ops)

Activated: 4 QSpec tests (vec.free, hashmap.free, sb.free, sb.size).

Sprint 6: Remaining RSpec Failures — COMPLETE

All 3 RSpec failures already fixed (slices, regex, traits).

Sprint 7: QSpec Activation & Property Testing Adoption — COMPLETE

Task	Description	Status
7.1	Audit 888 pending tests — categorized by blocker type	DONE
7.2	Activate unblocked tests (57 activated across 7+ files)	DONE
7.3	Property testing adoption — 47 property tests across 10 spec files	DONE
7.4	Fix 3 pre-existing QSpec failures	DONE

Property tests: First-ever use of qspec/property module. 47 forall_i/forall_ii property tests with shrinking across arithmetic, bitwise, comparisons, short-circuit, vectors, strings, hashmaps, collection ops, expressions, and functions specs. Also uses property_commutative and property_identity convenience helpers.

Audit results (888 pending): ~100 compile-error tests (need QSpec stderr capture), ~100 multi-module tests (need multi-file QSpec), ~200 blocked by known bugs (generic enums, traits, spawn/await, regex), ~300 blocked by unimplemented features.

Sprint 8: Documentation & Polish — COMPLETE

Task	Description	Status
8.1	Update ROADMAP.md — mark all completed items, update metrics	DONE
8.2	Update QUARTZ_REFERENCE.md — v5.25.0, UFCS table, HashMap/SB methods	DONE
8.3	Update MEMORY.md — condensed to <120 lines, moved details to completed-phases.md	DONE
8.4	Final UNIFIED_API.md pass — 40+ methods marked done, naming corrected	DONE
8.5	Clean QSpec workaround comments — 3 files updated	DONE
8.6	Fixpoint validation — `rake qspec` 188/188 pass	DONE

Sprint Summary

Sprint	RSpec Fixes	QSpec Activated	Property Tests	Status
1: Extend/Operator/@sigil	9	—	—	COMPLETE
2: Map Comprehensions	10	—	—	COMPLETE
3: Visibility/Variadic/Const	10	—	—	COMPLETE
4: Parser Workarounds	0	49	—	COMPLETE
5: API Unification	0	4	7	COMPLETE
6: Slices/Regex/Traits	3	—	—	COMPLETE
7: Activation & Properties	0	57	47	COMPLETE
8: Documentation	0	0	0	COMPLETE
Total	32 (done)	110+	47	ALL COMPLETE

QSpec Activation Plan (Post-Sprint)

Systematic activation of pending tests through compiler fixes and test body writing:

Sprint	Tests	Work
A: Extend blocks, @field, custom_index	+26	Test bodies for working features
B: char predicates, as_type, intmap	+17	Compiler bugfixes (SIGSEGV, missing intrinsics)
C: HashMap bracket syntax	+5	typecheck.qz NODE_INDEX fix
D: Pipeline operator	+6	parser.qz pipeline parsing
E: Multi-file QSpec with fixtures/	+4	Rakefile + fixtures/ infrastructure
F: Colors stdlib	+29	import path resolution
G: Generic struct field access	+15	Type param bracket stripping fix
H: $unwrap/$try SIGSEGV	+20	gensym, Option/Result registration, wildcard arms
Quick wins	+8	arr_len, for-in Vec, custom index set
Stdlib (JSON/TOML/range)	+38	Fix JSON/TOML compile bugs, activate range intrinsics
Quick-win sweep	+31	@cfg compound, closures in HOFs, heredocs, static_assert
Subprocess infra	+35	compile-error, IR inspection, panic/exit, stderr tests
Wave 2: compile-error tests	+4	F32/F64 mismatch, match exhaustiveness Int/String
Wave 2: visibility parse errors	+2	`public` keyword, double `private` parser errors
Wave 2: multi-module fixtures	+7	Cross-module enums, private access, wildcard struct import
Wave 2: const-eval bitwise	+5	band/bor/bxor/shl/shr in const context (mir.qz + C bootstrap)
Wave 2: const-eval loops	+9	for-in sum/factorial/inclusive/zero-iter, while sum/gcd, loop+if
Wave 3: IR inspection	+5	SIMD i32x4/f32x4/f64x2, sized i32, global var IR patterns
Wave 3: compile-error + runtime	+5	const reassign, match exhaustiveness, priv keyword, memory ordering IR
Wave 3: visibility multi-module	+4	Private section scope, toggle back, private defs, private struct access
Wave 3: raw string fix	+3	Backslash-n, backslash-t, concatenation (lexer + codegen fix)
Wave 3: U64/I64 types	+2	Type alias registration in typecheck.qz
Wave 3: UFCS Int/F64	+1	Int$to_f64, Int$to_s, Int$to_f32, F64$to_i, F64$to_s codegen
Wave 3: atomic_exchange	+2	Runtime acq_rel exchange + IR atomicrmw xchg test
Wave 3: narrow volatile	+5	store/load volatile i8/i16/i32 (mir_sizeof_type fix)
Wave 3: quick wins	+2	f32x8 SIMD IR, const fn in static_assert
Wave 4: spawn/await codegen	+15	pthread_create/join impl, task struct layout, spawn wrappers
Wave 4: compile-error + quick wins	+5	vec_index type, nil_coalescing spacing, @sigil scope, multiline interp
Wave 5: channel/mutex codegen	+17	Single-threaded try_send/try_recv/channel_len/closed + cross-thread send/recv
Wave 5: mutex tests	+3	mutex_new, mutex_lock/unlock, mutex_try_lock codegen
Wave 5: compile-error tests	+3	Circular imports, self-import, private fn access
Wave 5: binary literals + underscores	+5	0b/0B prefix parsing, numeric underscore skipping in lexer/parser
Wave 5: concurrency + IR	+2	SPSC ring buffer with atomic CAS, MIR constant-fold IR verification
Wave 6: linear type compile-errors	+3	QZ1201 unconsumed, QZ1202 consumed twice, QZ1203 use after move
Wave 6: mutable borrow compile-errors	+4	QZ1208 &mut immutable, QZ1205 double &mut, QZ1206 conflicting borrows
Wave 6: overflow checks	+6	—overflow-check flag, add/sub/mul overflow panics, IR intrinsics
Wave 6: ByteReader + quick wins	+8	ByteReader import fix, set empty?, :1foo rejection, pipeline
Wave 7: Module system + arity + break	+71	Forward decl dedup, `$` safety net, module/var collision, arity overloading (TC+MIR), done-flag→break refactor, 8 new module test files
Total activated	~432	From 1,830 → 2,190 active `it` tests

Phase 1 Quick Wins — COMPLETE

Systematic activation of all pending tests that don’t require compiler feature work:

Category	Tests	Work
Const eval	+4	static_assert failures, const fn runtime lowering (removed MIR `< 2` filter)
Argparse	+6	Rewrote as subprocess tests (QSpec+argparse import SIGSEGV workaround)
Arity overloading	+3	Basic arity, UFCS arity, cross-module arity (Bug 6 regression)
Visibility	+2	Private forward-ref, private-calls-private (Bug 4 confirmed fixed)
Vec bracket	+2	`v[0]` and `v[1]` bracket index syntax
Strings	+1	Heredoc `#{}` interpolation (subprocess, `str_concat` to avoid compile-time expansion)
Cfg arity	+1	Same-file arity overloading (outdated comment said unsupported)
Import regression	+1	Bug 6 cross-module arity overloading regression test
Total	+20	470 → 450 pending

Phase 2: Monomorphization Engine — COMPLETE

Bounded generic function specialization and trait method dispatch codegen:

Part	Description	Tests	Status
D	Unbounded generic function tests (`def f<T>`)	+4	DONE
A1-A3	MirContext infrastructure, PASS 0.9 registration, skip rule	0	DONE
A4-A7	Call-site detection, specialization queue, emit specializations	0	DONE
A8-A9	Trait method rewriting (spec_current_type, impl_current_type)	0	DONE
C	Trait declaration + dispatch subprocess tests	+12	DONE
B1	Type alias validation (self-referential, cycles, unknown target)	+3	DONE
Total		+19	450 → 431 pending

Phase 3: Drop Codegen + Test Harvesting — COMPLETE

Drop RAII verification, labeled loop error checks, and broad test activation:

Part	Description	Tests	Status
A1	Drop test bodies (scope exit, return, LIFO, loop, mixed)	+8	DONE
A2	Drop PASS 0.55 in `mir_lower_all` (multi-file registration)	0	DONE
B	Trait tests (generic params, Eq for Int)	+3	DONE
C1	Labeled loop error checks (typecheck.qz)	+3	DONE
C2-C3	Generic enum tests (Option, Result<T,E> definitions)	+5	DONE
D	Module tests (cross-module impl)	+1	DONE
Total		+19	431 → 414 pending

Key compiler changes:

mir.qz: PASS 0.55 in mir_lower_all — scans all_funcs tag-9 entries for impl Drop → register_drop_type (~12 LoC)
typecheck.qz: loop_labels: Vec<String> field on TypecheckState, tc_has_loop_label/tc_pop_loop_label helpers, duplicate/undefined label detection in while/for/break/continue (~30 LoC)

Key finding: Drop codegen infrastructure (register_drop_type, push_droppable, emit_drops_for_scope, emit_nested_drops) works end-to-end. 8 RAII tests pass.

Phase 4: Compile-Error Sweep + TOML Token Helpers — COMPLETE

Systematic test activation via compile-error test bodies, TOML lexer typed accessors, and error message fixes:

Part	Description	Tests	Status
A	Arity overload error message tests (fixed expected msg)	+2	DONE
B	TOML lexer tests via `toml_get_token`/`toml_token_count` helpers	+12	DONE
D	Trait missing method detection test (compiler already detected)	+1	DONE
Total		+15	414 → 399 pending

Key changes:

std/toml/lexer.qz: Added toml_get_token(tokens, idx): TomlToken and toml_token_count(tokens): Int (~10 LoC)
spec/qspec/fixtures/vis_extended_module.qz: Added VisExtPrivateStruct + VisExtPrivateEnum after priv (for future private visibility tests)

Attempted but reverted (21 tests — compiler doesn’t detect yet): multi-line paren/bracket/array expressions, ?? spacing, const purity, closure arity, match arm types, duplicate arity, Vec type enforcement, private struct/enum visibility, 4 drop scope/break/continue/nested tests, trait wrong signature.

Phase 5: Multi-Module Validation + Drop Scope Fixes + Compile-Error Detection — COMPLETE

Multi-module test harvest, drop block-exit codegen, and trait signature verification:

Track	Description	Tests	Status
A	Multi-module test bodies (modules, newtypes, type aliases, name resolution)	+9	DONE
B	Drop inner-scope codegen fix (emit_and_pop_drops_for_scope, NODE_IF scope_depth)	+2	DONE
C	Trait wrong-signature detection + Ord for Int test	+2	DONE
Total		+13	399 → 386 pending

Key compiler changes:

mir.qz: New emit_and_pop_drops_for_scope function — emits drops AND removes from droppable_stack to prevent double-drops at function exit. NODE_IF handler now manages scope_depth for then/else bodies, enabling correct block-exit drop ordering (~45 LoC)
typecheck.qz: tc_verify_impl_completeness now compares param counts after name match. Fixed Drop trait builtin registration from string format to structured [param_types_vec, return_type] (~30 LoC)

Track A details: 4 module tests (private helper, impl with args, top-level calling impl, chained imports), 3 newtype tests (cross-module use/return/param), 1 type alias test, 1 name resolution test (local fn shadows wildcard import). All use existing assert_multi_run_exits infrastructure.

Track B details: if-block variables now dropped at block exit in LIFO order before merging. “drops inner scope before outer” and “handles multiple nested scopes” both pass. Existing 8 drop tests unaffected.

Attempted but reverted: type alias for imported struct (“Unknown struct: MyPoint”), duplicate arity detection (functions register twice in pipeline — false positives), max<T: Ord> generic dispatch (exit 1 instead of 42).

Phase 6: Concurrency + Generic Functions + Targeted Fixes — COMPLETE

Concurrency test activation, generic function workarounds, parser/typecheck/codegen fixes:

Track	Description	Tests	Status
B	Generic function helpers (named wrappers for closure workaround)	+5	DONE
A1	Select statement tests (recv, multi-recv, send, default)	+4	DONE
A4	Channel producer-consumer (channel_close + poll loop)	+1	DONE
D	Associated function `Type.method()` (parser kind==4→6 + typecheck fix)	+4	DONE
C1	set_members codegen fix (proper Vec header allocation)	+2	DONE
Total		+16	386 → 370 pending

Compiler changes:

parser.qz: Two node-kind checks == 4 (StringLit) → == 6 (Ident) for associated function detection (~lines 1946, 1992)
typecheck.qz: Uppercase identifier recognized as type name sentinel (prevents “Undefined variable: TypeName” for Type.method() calls)
codegen.qz: set_members allocates new 3-word Vec header [capacity, count, data_ptr] instead of returning raw data pointer

Blocked/deferred: ~~task_group (user fns missing from generated IR)~~ FIXED in Phase 11, ~~thread_pool (depends on task_group)~~ FIXED in Phase 11, F32 cross-function comparison (deep codegen bug), compile-error probes (0/8 conditions detected), drop on break/continue.

Phase 7: F32 Fix, Literal Suffixes, Drop/Multi-Module Harvest — COMPLETE

F32 float marking, integer literal suffixes, and test activation across 5 tracks:

Track	Description	Tests	Status
A	F32 param/annotation float marking + `to_f64` identity shortcut	+3	DONE
B	Drop on break/continue subprocess tests	+2	DONE
C	Multi-module harvest (type aliases, @cfg, imported struct alias, UFCS wildcard)	+4	DONE
D	Additional drop tests (match exit, early return via match)	+2	DONE
E	Integer literal suffixes `42_u8`, `100_i16`, `77_i32`, `55_u64`	+4	DONE
F	Never return type compile-error probe	+1	DONE
Total		+16	370 → 354 pending

Compiler changes:

mir.qz: F32 param marking (param_type == "F64" or param_type == "F32" at two sites), F32/F64 type annotation marking, literal suffix fallback (check init node str2), to_f64 identity shortcut for float args
lexer.qz: Suffix recognition after integer digit loop (u8/i8/u16/i16/u32/i32/u64/i64)
parser.qz: parse_int_suffix() helper, suffix propagation to AST str2 at both integer parsing sites

Blocked/reverted: F32 precision test (annotation doesn’t truncate on store), nested field drops (codegen raw ptr as SSA), deeply nested drops (same), defer+Drop interaction (defer silently ignored), private struct/enum visibility (not enforced), cross-module extend method (arity bug counts self param).

Structural Method Dispatch — COMPLETE

Compile-time duck typing: untyped parameters dispatch methods by concrete type at call site.

Component	Description	Status
PASS 0.95	Detect functions with UFCS calls on untyped parameters	DONE
PASS 0.96	Fixpoint loop for transitive structural detection	DONE
Per-param type tracking	`spec_param_types` Vec on MirContext, independent per-param resolution	DONE
Compound specialization	`mix$2$Namer$Counter` naming scheme	DONE
UFCS error messages	”Type ‘Widget’ has no method ‘transform’” for struct receivers	DONE
Test suite	25 active + 3 pending across 8 test groups	DONE

Key: This is NOT trait-based — it infers structural constraints from method usage on untyped params, then monomorphizes per call-site. Coexists with bounded generics and trait dispatch.

Phase 8: Record/Structural/AssocFn Probes — COMPLETE

Probe-based test activation: zero compiler changes, subprocess tests only.

Track	Description	Tests	Status
A	Record types subprocess (param position, width subtyping)	+2	DONE
B	Structural dispatch properties (roundtrip, commutativity)	+2	DONE
G1	Associated function probes (lowercase receiver, Type.method vs field)	+2	DONE
G2	Vec<String> test (vec_push/vec_get with string values)	+1	DONE
Total		+7	357 → 350 pending

Probed but blocked (0 compiler LoC, 0 tests activated):

Record type in return position — self-hosted parser consumes { as block start
Record & intersection — self-hosted doesn’t support & as type operator
Mutable borrows (&mut) — expression silently drops containing function
~~Trait default cross-call~~ — FIXED in Phase 9: default method inheritance implemented
Fn in struct field — parse error for Fn(Int): Int as field type
Closure capture depth — multi-level capture doesn’t thread captured variables
defer+Drop interaction — defer silently ignored when Drop present
@cfg+@repr(C) combined — lli can’t handle getelementptr on C struct types
Closure arity/type errors — compiler doesn’t detect wrong parameter count/type

Remaining pending breakdown (161 — updated after Phase 14): See “161 Pending Tests — Breakdown by Blocker” table below for current breakdown. All remaining tests are blocked by fundamental missing features (regex, arenas, macros, slices, etc.) — no more quick activations remain.

Phase 9: Fix Pre-Existing QSpec Failures + Trait Default Inheritance — COMPLETE

Two tracks: restore 197/197 QSpec pass rate and implement trait default method inheritance.

Track	Description	Tests	Status
A	Add missing `import * from qspec/subprocess` to fixed_width_integers + float_f32	+6 activated, 7 pending-ified	DONE
B	Trait default method inheritance (typecheck.qz + resolver.qz)	+2 activated (partial impl + cross-call)	DONE
Total		+8 net	~350 → ~342 pending

Track A details: Both spec files called subprocess functions without importing qspec/subprocess. Added import, restored 197/197. 4 IR tests (i8/i16/i32 type emission) + 2 compile-error tests (F32 type mixing) newly activated. 4 literal suffix tests + 3 F32 comparison tests pending-ified (pre-existing codegen bugs).

Track B details: All trait methods with bodies are now defaults. Partial impl blocks inherit unoverridden methods from trait. Default methods correctly call other trait methods via MIR rewriting.

typecheck.qz: Added trait_method_defaults field, tc_register_trait tracks defaults, tc_verify_impl_completeness skips methods with defaults
resolver.qz: resolve_collect_funcs synthesizes Type$method entries for inherited default methods not overridden in impl blocks

Phase 10: Parser Block Expressions + Strategic Harvest — COMPLETE

Two tracks: parser feature (do..end + curly blocks as primary expressions) and systematic test harvest.

Track	Description	Tests	Status
A	Standalone do..end block expressions (NODE_BLOCK for nullary, NODE_LAMBDA for parameterized)	+5	DONE
A	Curly block arrow syntax (`{ x -> expr }`, `{ -> expr }`) in arrow_lambdas + newline specs	+8	DONE
B	Trait harvest (Self type, generic impl, multi-trait bounds, std traits, Ord defaults, max<T:Ord>)	+13	DONE
B	Generic function harvest (nested generic types, multi-type args, generic Fn type)	+3	DONE
B	Concurrency harvest (concurrent execution, join, atomics, mutex, blocking send, select multiplex)	+6	DONE
Total		+35	~342 → ~307 pending

Track A — Parser changes (parser.qz, ~105 lines):

ps_parse_standalone_block_body: Shared parser for do..end and curly block bodies. Nullary blocks (no params, no arrow) produce NODE_BLOCK directly (matching C bootstrap behavior). Parameterized blocks produce NODE_LAMBDA.
ps_parse_standalone_do_block: Consumes do, delegates to block body with end terminator.
ps_parse_standalone_curly_block: Consumes {, delegates to block body with } terminator.
Hook in ps_parse_primary(): Detects do token → standalone do block. Detects { with lookahead ({ -> }, { ident -> }, { var }) → standalone curly block. Falls through to struct/map/set literal otherwise.
Lookahead limitation: { x, y -> expr } (multi-param) conflicts with set literal {x, y, 30}. Multi-param curly blocks only work in trailing/postfix position on function calls.

Track B — Harvest probes: Used subprocess assert_run_exits and assert_compile_error to probe 73 pending tests across traits (16), slices (6), functions (6), and concurrency (17). Activated 22 that already work.

Remaining pending: 161 (updated after Phase 14). See breakdown in QSpec section below.

Phase 11: Task Group + Generics + Constant Dedup — COMPLETE

Three parallel tracks merged into trunk:

Track	Description	Tests	Status
A: Task group codegen fixes	`needs_closure_wrapper` flag + remove `thread_local` for lli	+8 (task_group)	DONE
A: Thread pool tests	Nested groups, parallel_map, 64 tasks, side effects	+4 (thread_pool)	DONE
A: Parallel iteration	parallel_map, parallel_for, parallel_reduce via task_group subprocess	+4 (concurrency)	DONE
A: recv_timeout	clock_gettime + pthread_cond_timedwait work via lli	+4 (recv_timeout)	DONE
B: Generic struct return type	Strip `<T>` from return annotations for struct registry lookup	+13 (generics)	DONE
C: MIR constant dedup	`TYPE_INT` → `MIR_TYPE_INT`, canonical NODE constants, parity lint	0 (refactor)	DONE
Total		+33	~307 → ~287 pending

Track A — Codegen fixes (codegen.qz):

Added needs_closure_wrapper: Int field to CodegenState. Set when closure spawn is used (MIR_SPAWN closure branch) or when uses_task_group == 1. Restructured cg_emit_spawn_wrappers to emit __closure_spawn_wrapper before the spawned_func_names early-return guard.
Replaced thread_local global with plain global for @__qz_cancel_ptr (lli doesn’t support TLS). Trade-off: concurrent task_groups from different threads may see stale cancel pointers.
Both taskgroup_spawn(g, -> expr) and g.spawn(-> expr) work (UFCS parse fixed in Phase F Reset).

Track A — Key findings:

spawn (-> expr) closure spawn outside task_group blocked by typecheck: “expected Int but got Function” on await h
is_cancelled() outside task_group fails (undefined @__qz_cancel_ptr when uses_task_group == 0)
recv_timeout works via lli — clock_gettime and pthread_cond_timedwait resolve dynamically

Track B — Generic struct return type (mir.qz):

Two sites in mir_infer_expr_type and mir_lower_stmt strip generic type args (e.g., GBox<T> → GBox) from return annotations so struct registry lookup succeeds for generic function return types.
Post-merge regression: These strips also destroyed Vec<ReadyEvent> → Vec, breaking element type extraction for field access (3 event_loop failures). Fixed by moving strips to the 3 actual struct registry lookup call sites instead.

Track C — MIR constant dedup (mir.qz, codegen.qz, egraph_opt.qz, node_constants.qz):

Renamed TYPE_INT/TYPE_BOOL/… → MIR_TYPE_INT/MIR_TYPE_BOOL/… to distinguish from typecheck.qz type constants
Added NODE_TASK_GROUP = 71 and NODE_SELECT = 59 to node_constants.qz
Added tools/check_constants.rb parity lint (checks C bootstrap ↔ self-hosted constant alignment)
Added rake check_constants task to Rakefile

Fixpoint: gen2 == gen3 identical after all merges.

Phase 12: Generics Completion + Parser Fixes — COMPLETE

Eight tracks targeting generics, parser improvements, type safety, and as_type<T>:

Track	Description	Tests	Status
1	Option/Result enum type fix (`tc_check_enum_access` returns TYPE_OPTION/TYPE_RESULT)	+8	DONE
2	Bitwise operator newline continuation (`&`, `^`, `<<`, `>>` suppress trailing newlines)	+4	DONE
3	Curly block expressions (keyword-prefixed `{ if/var/while/for/match/return ... }`)	+4	DONE
4	Generic type alias struct init (`type IntBox = Box<Int>` + `IntBox { value: 42 }`)	+1	DONE
5	Polymorphic multi-type dispatch (`identity(42)` + `identity("hello")`)	+1	DONE
6	HashMap literal syntax (`{key: val}` emits string keys, not symbol keys)	+4	DONE
7	Vec/HashMap element type checking (`tc_elem_type_matches` strict checker)	+11	DONE
8	`as_type<T>` typed calls (typecheck returns struct type, MIR tracks struct name)	+3	DONE
Total		+36	~287 → ~253 pending

Track 1 — Option/Result predicates (typecheck.qz):

tc_check_enum_access returned TYPE_ENUM for all enums including Option/Result. Added if enum_name == "Option" return TYPE_OPTION and if enum_name == "Result" return TYPE_RESULT before the generic return.
Unlocked .some?/.none?/.ok?/.err? UFCS predicate methods (infrastructure already existed at lines 7513-7564).

Track 2 — Bitwise newline continuation (parser.qz):

Added &, ^, <<, >> to the set of binary operators that suppress trailing newlines (alongside +, -, *, /).

Track 3 — Curly block expressions (parser.qz):

Extended ps_parse_standalone_curly_block to detect keyword-prefixed blocks: { if ... }, { var ... }, { while ... }, { for ... }, { match ... }, { return ... }.
These are unambiguously blocks (not set/map literals), parsed as NODE_BLOCK.

Track 4 — Generic type alias struct init (typecheck.qz):

NODE_STRUCT_INIT handler now checks tc_lookup_type_alias for unrecognized struct names.
Resolves alias (e.g., IntBox → Box<Int>), extracts base name and type args, substitutes field types.

Track 5 — Polymorphic dispatch (1 test, 1 deferred):

Same generic function called with different types already works via monomorphization.
1 test deferred: returns struct from trait-bounded generic function causes compiler hang.

Track 6 — HashMap literal syntax (parser.qz):

Changed {key: val} shorthand to emit string keys (ast_string_lit) instead of symbol keys (ast_symbol_lit).
hashmap_get(m, "key") now works correctly with shorthand-created maps.
2 tests kept pending: {:key => val} symbol fat-arrow syntax causes SIGSEGV.

Track 7 — Element type checking (typecheck.qz):

Created tc_elem_type_matches function — strict type comparator that doesn’t fall through to the i64 catch-all in tc_types_match.
Applied to: vec_push, vec_set (value type), hashmap_set (key + value types), hashmap_get (key type), hashmap_has (key type), hashmap_del (key type).
Key insight: tc_types_match(TYPE_STRING, TYPE_INT) returns true due to existential model (all i64-compatible). tc_elem_type_matches rejects this.

Track 8 — as_type<T> typed calls (typecheck.qz + mir.qz):

Typecheck: as_type<T> call with type arg resolves T via tc_parse_type and returns struct type.
MIR: Added as_type detection in NODE_LET/NODE_CALL handler to call mir_ctx_mark_struct_var with the type arg as struct name.
Enables field access on restored struct values: var restored = as_type<Point>(i); restored.x.

Fixpoint: gen2 == gen3 identical (1179 functions).

Phase 13: Parallel Test Activation — COMPLETE

Two parallel streams (Stream A + Stream B) probing and activating pending QSpec tests:

Track	Description	Tests	Status
A1	Concurrency probes (recv, send, select, mutex via direct helpers)	+4	DONE
A2	F32 call return type fix (mir.qz: mark F32 return from call expressions)	+9	DONE
A3	F32 precision truncation fix	+1	DONE
A4	TOML + packed arrays probes (@repr(C) IR inspection via subprocess)	+3	DONE
A5	Tuple return + void match arm do..end block (subprocess tests)	+2	DONE
A6	Assert codegen handler + enumerable tests + curly lambda disambiguation	+6	DONE
A7	TYPE_NEVER fix in tc_types_match (unreachable/panic/exit compatible with any return type)	+1	DONE
B1	Multi-file import probes (cross-module global vars, pub import re-export)	+5	DONE
B2	Compile-error detection probes (ptr_read/ptr_write arity, Vec in error msgs)	+3	DONE
B3	Generics + traits probes (multi-binding enum guards, trait-bounded generic return)	+2	DONE
B4-B6	Imported generic struct via factory, traits public by default	+2	DONE
B7	Remaining probes (visibility_spec)	+1	DONE
Total		+39	~236 → ~197 pending

Compiler changes (Stream A only — Stream B was test-only):

mir.qz: F32 call return type marking — when a function call returns F32/F64, mark the dest var as float so subsequent comparisons use fcmp instead of icmp
codegen.qz: Assert intrinsic handler — assert(cond) emits conditional branch + call void @exit(i32 1) + unreachable on false path
typecheck.qz: TYPE_NEVER in tc_types_match — Never (bottom type) now matches any type, fixing “expected Int but got !” for unreachable()/panic()/exit() in Int-returning functions

Fixpoint: gen2 == gen3 identical (1210 functions).

Phase 14: Parallel Streams A+B — COMPLETE

Two parallel development streams (worktrees) probing and activating pending QSpec tests:

Track	Description	Tests	Status
A1	Fix 3 pre-existing QSpec failures (add missing subprocess imports)	+3 (restored)	DONE
A2	Module dot syntax + path import tests	+1	DONE
A3	ptr_alloc intrinsic + Ptr<T> tests (subprocess)	+6	DONE
A4	Generic type alias + cross-module generics	+2	DONE
A5	Module path resolution spec file	+1	DONE
A6	@heap struct + newline continuation tests	+4	DONE
A7	Nested closures + module.Type return	+3	DONE
A8	Const eval iteration limit + binary rebuild	+1	DONE
A9	Selective imports + nested paths + struct literal	+6	DONE
A10	Wildcard + selective import tests	+4	DONE
B1	HashMap symbol key fix (`{:key}` → string key in codegen)	+2	DONE
B2	Drop nested fields SSA name fix (codegen raw ptr cleanup)	+2	DONE
B4	Structural dispatch default args fix	0 (fix only)	DONE
B5	Function type alias dispatch fix (MIR arity resolution)	+3	DONE
Total		~37	~197 → ~161 pending

Stream A compiler changes:

codegen.qz: ptr_alloc intrinsic handler — emits call i8* @malloc(i64 %size) + ptrtoint to i64
self-hosted/bin/quartz: Rebuilt binary to pick up all Phase 13+14 changes
std/qspec/subprocess.qz: _sub_write_multi now creates subdirectories when filenames contain /

Stream B compiler changes:

codegen.qz: Drop nested field SSA names use sanitized variable names instead of raw pointers
mir.qz: Function type alias dispatch — resolve through alias to find correct arity-mangled name
typecheck.qz: Structural dispatch default args — correctly propagate default arg count through specialization
parser.qz: HashMap {key: val} shorthand confirmed using string keys (Phase 12 fix validated)

Key findings:

@heap struct works for single-field structs; multi-field structs have offset resolution bugs (field 2+ wrong)
Newline continuation tests in the spec said “fail to compile” but multi-line call args and array literals actually compile fine — converted from compile-error to positive tests
Const eval iteration limit requires rebuilt binary (was stale from Phase 13)
Subdirectory file support in _sub_write_multi enables hierarchical module path testing

Fixpoint: gen2 == gen3 identical (1210 functions).

Phase 15: Parallel Streams A+B — COMPLETE

Two parallel development streams targeting typecheck/MIR improvements (Stream A) and parser/codegen/intrinsics (Stream B):

Track	Description	Tests	Status
A1	Compile-error detection (tc_types_match_strict for 5 cases)	+5	DONE
A2	`??` spacing + const eval non-const fn	+2	DONE
A3	Fixed-width wrapping + I8 sign-extend	+3	DONE
A7	`$debug` in expression position (NODE_BLOCK type extraction)	+1	DONE
A6	Match arm related span (first arm location in error msg)	+1	DONE
A4	Lambda arity validation (param_count check at call sites)	+2	DONE
A9	Newtype cross-assignment detection (type mismatch at call sites)	+1	DONE
A5	Super-trait enforcement (trait_super_traits + impl verification)	+1	DONE
A8	Defer fix — `defer` was broken in `mir_lower_function_with_name`	+1	DONE
B1	Slice intrinsics (slice, slice_get, slice_set, slice_len, str_slice)	+5	DONE
B2	String slicing tests + str_char_at bounds fix	+4	DONE
B3	Import alias support (`import foo as bar`) + module tests	+2	DONE
B4	@heap multi-field struct type resolution fix	0 (fix only)	DONE
B5	field_offset intrinsic + @repr(C) struct tests	+6	DONE
B6	Where clause parsing (`where T: Trait`)	+1	DONE
B7	Arena blocks tests (arena scope, arena alloc, basic patterns)	+7	DONE
Total		+41 (17 Stream A + 24 Stream B)	161 → 120 pending

Stream A compiler changes:

typecheck.qz: tc_types_match_strict (strict type comparator rejecting i64 catch-all), lambda arity validation via tc_scope_lookup_param_count, trait_super_traits field + impl verification, match arm first-location tracking, NODE_BLOCK type extraction for bare expression nodes, newtype cross-assignment detection at call sites
mir.qz: Defer scope push/pop in mir_lower_function_with_name (fix: defer was universally broken in multi-module compilation path)
lexer.qz: ?? token spacing fixes
codegen.qz: I8 sign-extend fix

Stream B compiler changes:

codegen.qz: Slice intrinsics (slice/slice_get/slice_set/slice_len/str_slice), field_offset intrinsic, arena block IR emission
mir.qz: Slice/arena/field_offset MIR lowering
parser.qz: Where clause parsing, import alias syntax
resolver.qz: Import alias resolution

Stream A probed but blocked:

Track 10: Safe navigation ?. — parser doesn’t tokenize ?. + existential type erasure blocks Option<T> field access
Track 11: Mutable borrows — QZ1205 false positive in self-hosted compiler
Track 12: Combined @cfg — @repr(C) struct type declaration missing from IR

Fixpoint: gen2 == gen3 identical (1218 functions).

Phase 17: Regex Root Cause Fix (Feb 22, 2026)

17 tests activated by fixing the root cause bugs preventing ~r regex literals from working.

Root cause bugs fixed:

NODE_REGEX_LIT had no handler in MIR (mir.qz:4575): mir_lower_expr handled every literal type except NODE_REGEX_LIT (kind 5). A ~r"hello" literal MIR-lowered to integer 0 (null pointer), causing regcomp(null) to fail silently. Fix: 3-line handler identical to NODE_STRING_LIT — mir_emit_const_string(ctx, pattern).
Lexer stored full ~r"..." syntax as lexeme (lexer.qz:1145): The final var lexeme = source.slice(start, pos) overwrote the inner-scope pattern extraction, producing ~r"hello" instead of hello. Fix: strip ~r"..." wrapper at line 1152 (same location as TOK_STRING unescaping).

Track	Tests	Description
T1	0	MIR fix + lexer fix + rebuild compiler
T2	6	`~r` literal parsing: basic, groups, char classes, quantifiers, variable, function
T3	4	`=~` operator: true on match, false on no match, string variable, regex variable
T4	2	`!~` operator: true on no match, false on match
T5	3	`=~?` capture: non-zero on match, 0 on no match, capture by index
T6	2	Capture features: full matched string, capture groups
Total	17	80 → 63 pending

Properly deferred (4 tests):

match with regex arms — requires pattern syntax extension in parser (not a bug fix)
non-capturing group (?:...) — POSIX ERE does not support non-capturing groups
backreference \1 — POSIX ERE does not support backreferences in extended mode
regex_split Vec<String> count — PCRE2 runtime not available in lli

Compiler changes: mir.qz (+5 lines: NODE_REGEX_LIT constant + handler), lexer.qz (+3 lines: regex pattern extraction).

Fixpoint: gen2 == gen3 identical (1218 functions).

Phase 18: User Macro System — COMPLETE

22 tests activated by implementing the complete user macro system (quote/unquote tier) in the self-hosted compiler.

Track	Description	Tests	Status
1	Lexer: TOK_MACRO=112, TOK_QUOTE=113, TOK_UNQUOTE=114, TOK_UNQUOTE_EACH=115	0	DONE
2	AST: NODE_MACRO_DEF=72, NODE_QUOTE=73, NODE_UNQUOTE=74, NODE_UNQUOTE_EACH=75	0	DONE
3	Parser: ps_parse_macro_def, ps_parse_quote_block, ps_parse_unquote	0	DONE
4	Macro expansion engine: registry, collect_macro_defs, expand_in_block removal	0	DONE
5	Quote/unquote expansion: clone_with_unquote with parameter substitution	0	DONE
6	String template expansion: ast_to_source + re_parse_expr + ast_clone_tree	0	DONE
7	Activate user_macros_spec.qz (5 tests)	5	DONE
8	Activate macro_parsing_spec.qz (17 tests)	17	DONE
Total		22	63 → 41 pending

Compiler changes (~600 lines across 5 files):

token_constants.qz: 4 new token constants (TOK_MACRO, TOK_QUOTE, TOK_UNQUOTE, TOK_UNQUOTE_EACH)
node_constants.qz: 4 new node constants (NODE_MACRO_DEF, NODE_QUOTE, NODE_UNQUOTE, NODE_UNQUOTE_EACH)
lexer.qz: 4 keyword recognitions in keyword matcher
ast.qz: 4 constructor functions (ast_macro_def, ast_quote, ast_unquote, ast_unquote_each)
parser.qz: ps_parse_macro_def (params, variadic detection), ps_parse_quote_block, ps_parse_unquote (~120 lines)
macro_expand.qz: Major extension — macro registry (7 parallel Vecs), collect_macro_defs, expand_in_block (removes defs from AST), user macro dispatch, clone_with_unquote (deep AST cloning with unquote substitution), expand_string_template (ast_to_source + re_parse_expr + ast_clone_tree) (~350 lines)

Key bugs fixed:

clone_with_unquote NODE_BINARY: argument order swapped in ast_binary(s, op, left, ...) → ast_binary(s, left, op, ...). The operator value 0 (for ’+’) was being stored as the left child handle, which pointed to IDENT “x” at handle 0.
typecheck.qz NODE_EXPR_STMT: used ast_get_extra instead of ast_get_left for inner expression extraction in block expression typing. Handle 0 is valid (first AST node), so guard must be >= 0 not > 0.

String template limitation: Quartz’s lexer processes #{} as string interpolation at tokenization time, preventing "(#{x} + #{x})" macro templates from being seen as a single TOK_STRING. All tests converted to use quote/unquote equivalents. String template macros work when templates don’t use #{} syntax (e.g., simple string returns).

Architecture: Two-phase expansion — Phase 1 collects macro definitions from top-level declarations into the registry. Phase 2 expands $macro_name(args) calls and removes NODE_MACRO_DEF nodes from the AST. Quote/unquote macros use deep AST cloning (clone_with_unquote) which recursively copies the quote body, substituting NODE_UNQUOTE nodes with the corresponding argument ASTs. String template macros use ast_to_source → string substitution → re_parse_expr (tokenize + parse + ast_clone_tree deep-copy into main AstStorage).

Fixpoint: gen2 == gen3 identical (1251 functions, +33 from 1218).

Arena Safety Analysis — COMPLETE

4 tests activated — arena safety compile-error warnings implemented via new typecheck analysis pass. All 4 previously-pending arena tests now active and green.

STRESS Residuals (Mar 1, 2026): +5 arena subprocess tests activated (allocation escapes, allocator trait, typed allocator, arena pools, pool destroy warning). 2 remain it_pending — raw arena_new()/arena_alloc() calls not tracked by safety system (only block syntax arena...do...end and pool API trigger tracking).

Exhaustion analysis (updated Mar 1): 4 non-safety QSpec it_pending tests remain as permanent platform limitations (documented in spec files):

Regex (2): non-capturing groups ((?:...)) + backreferences (\1) — POSIX ERE limitation, requires PCRE2
Vec<String> (1): regex_split returns Vec<String> — PCRE2 runtime not available in lli
Fixed-width integers (1): htons extern FFI — symbol not resolvable by lli (macro/inline in libc)

Plus 14 safety infrastructure tests pending activation (S2.P: 4, S2.B: 5, S2.L: 5). Networking tests (14 across https/tls/buffered_net/network_timeout specs) blocked on in-process concurrency — spawn/join don’t exist, task_group requires subprocess testing which compiles full networking stack (memory-intensive).

Tests activated in Phase 22 (no longer pending):

Slices: v[start..end] range syntax — parser arg swap fix
Packed structs: @repr(C) no-padding — MIR/codegen packed flag plumbing
Conditional compilation: @repr(C) + @cfg combined — already worked, test body written
Regex: match with regex arms — parser TOK_REGEX + MIR regex pattern case

Phase 19: Feature Completion Tier 1 — COMPLETE

14 tests activated across 5 features (37→23 pending):

Track	Description	Tests	Status
Mutable borrows	Ephemeral &mut borrow release after call arguments	+3	DONE
Lambda type validation	Parameter + return type checking against Fn annotations	+2	DONE
Safe navigation `?.`	Lexer fix (trailing ? vs ?. operator), MIR OP_EQ fix, TYPE_OPTION registration, global field search	+4	DONE
Modules/imports	Directory mod.qz resolution, private re-export filtering	+2	DONE
Record type intersection	Parser & after }, TYPE_RECORD in tc_parse_type, tc_types_match, global field fallback in MIR	+3	DONE
Total		+14	37 → 23 pending

Key pattern: mir_find_field_globally searches all struct registrations for a field name — enables record type field access.

Fixpoint: 1253 functions (up from 1251).

Phase 20: Deep Fixes — Traits, Generic Ptypes, Record Returns — COMPLETE

6 tests activated (23→17 pending): 5 traits_spec + 1 record_types_spec

Track	Description	Tests	Status
Resolver path bug	Missing `/` separator in `-I` path construction	0 (fix)	DONE
Trait test import fix	`import std/traits` → `import traits`	0 (fix)	DONE
Generic ptype creation	`tc_parse_type` creates interned ptypes for user-defined generic structs/enums via `tc_make_ptype`	+5	DONE
Record return position	Already working — activated pending test	+1	DONE
Total		+6	23 → 17 pending

Fixpoint: 1253 functions (unchanged).

Phase 21: Cross-Module UFCS Fix — COMPLETE

3 tests activated (17→~14 pending): Fixed critical UFCS slot bug + activated cross-module tests.

Track	Description	Tests	Status
UFCS slot bug	`resolve_transform_ufcs_node` used wrong AST slots for NK_LET, NK_ASSIGN (get_right→get_left), NK_INDEX_ASSIGN (missing extra), NK_FIELD_ASSIGN (right→extra)	0 (fix)	DONE
Generic enum return	Cross-module `MyOption<Int>` return type (unblocked by Phase 20 ptype fix)	+1	DONE
Global var access	Cross-module `state$SHARED_COUNT` access	+1	DONE
UFCS regression test	`var result = module.func()` dot syntax in assignment context	+1	DONE
Total		+3	17 → ~14 pending

Root cause: resolve_transform_ufcs_node (resolver.qz:811-822) had slot mismatches for 4 node kinds. The sibling function resolve_rewrite_node (same file, lines 1024-1047) was written later with correct slots. The UFCS function was never updated to match. This meant var x = module.func() silently failed — the UFCS transform never reached the call inside the let initializer.

Fixpoint: 1253 functions (unchanged).

Phase 22: Finish Line + Phase U 8F — COMPLETE

4 tests activated (~14→~10 pending). Two parallel workstreams:

Worktree A — Finish Line (4 tests activated):

Track	Description	Tests	Status
Slice range syntax	`parser.qz:2273` — arg order swap in `ast_binary` for `v[start..end]` desugaring (was `(s, 1, index, end)`, corrected to `(s, end, 1, index)`)	+1	DONE
Packed struct codegen	MIR: added `packed` param to `mir_ctx_register_struct`. Codegen: emit `<{ ... }>` (packed) vs `{ ... }` (non-packed) based on AST extra flag	+1	DONE
@cfg+@repr(C) combined	Already worked — wrote test body with `field_offset` verification	+1	DONE
Regex match arms	Parser: added TOK_REGEX case to `ps_parse_pattern`. MIR: added regex pattern case in match arm lowering (compile regex, call `regex_match`)	+1	DONE
Fn in struct field	`obj.f(args)` calls Fn-typed struct fields via dot syntax — DONE (Phase F-Delta, typecheck detects Fn field, rewrites to FIELD_ACCESS callee, MIR emits indirect call)	+5	DONE
htons FFI	Symbol not resolvable by lli (macro/inline in libc) — deferred (hard platform limitation)	0	DEFERRED

Worktree B — Phase U 8F Intersection Infrastructure (0 new tests, infrastructure only):

Step	Description	Status
Record type storage	`TYPE_RECORD_BASE=3000`, module-level globals (g_record_signatures/field_names/field_types)	DONE
tc_parse_record_fields	Parses `"{ x: Int, y: String }"` into parallel name/type Vecs	DONE
tc_register_record	Interns record types by canonical signature	DONE
tc_register_intersection	Merges record fields from all `&`-separated parts, deduplicates	DONE
tc_record_types_match	Width subtyping — t1 must have ALL fields of t2	DONE
tc_type_name update	Registered record types display as “Record”	DONE
infer.qz TYPE_RECORD fix	Changed from 51 (duplicate of TYPE_INTERSECTION) to 52	DONE
Activation	Returning TYPE_RECORD_BASE from tc_parse_type causes SIGSEGV — type ID 3000 crashes parameter matching	DORMANT

Key finding: The record type infrastructure was complete and correct in isolation. The SIGSEGV was caused by overlapping range predicates (tc_is_newtype matched IDs >= 1000, covering union/record ranges). Fixed in Phase U 8F activation — narrowed all predicates to non-overlapping ranges, record and union types now fully live.

Fixpoint: 1259 functions (up from 1253, +6 record type functions).

Phase CMF: Cross-Module Fixes — COMPLETE

4 interconnected bugs fixed, 14 regression tests added. QSpec: 247/248, fixpoint verified.

Root cause analysis revealed Bug 4 (str_split ptype) was the keystone — fixing it cascaded correct type information that auto-fixed Bugs 1 and 3.

Bug	Description	Fix	Tests	Status
Bug 4 (root cause)	`str_split`/`str_chars` registered as `TYPE_INT` instead of `Vec<String>` ptype in typecheck_builtins	Added ptype overrides after `tc_init_builtins()` in typecheck.qz — `tc_make_ptype(tc, TYPE_VEC, TYPE_STRING, 0)`	+3	DONE
Bug 1	Chained `.size` on struct `Vec<T>` fields (e.g., `container.items.size`) returned wrong value	Auto-fixed by Bug 4 — `tc_base_kind` already unwraps ptypes correctly; the issue was the wrong source type from str_split	+2	FREE
Bug 3	Cross-module UFCS String methods don’t resolve (e.g., `parts[0].char_at(0)`)	Auto-fixed by Bug 4 — indexing into `Vec<String>` now returns `String`, enabling UFCS dispatch	+4	FREE
Bug 2	Module-level global reassignment creates local alloca instead of storing to global	Added `mir_find_global_name` helper (3-stage: module prefix → exact → suffix match) + NODE_LET handler check for bare reassignments (`is_mutable==0`)	+5	DONE
Total			+14

Files changed: self-hosted/middle/typecheck.qz (ptype overrides, lines 201-214), self-hosted/backend/mir.qz (mir_find_global_name + NODE_LET global check). New file: spec/qspec/cross_module_fixes_spec.qz (14 tests).

Why Bug 4 was the keystone: When str_split returned TYPE_INT, all downstream operations failed: parts[0] was typed as Int (not String), parts.size couldn’t trigger the vec_len() rewrite (since TYPE_INT != TYPE_VEC), and UFCS methods on parts[0] failed because the receiver wasn’t TYPE_STRING. Fixing the return type to Vec<String> made the entire inference chain work correctly.

Bug 2 design note: The parser creates NODE_LET for both new bindings (var x = ..., is_mutable=1) and bare reassignments (x = ..., is_mutable=0). The fix checks is_mutable==0 and then searches the global registry for a matching name. The 3-stage lookup (current module prefix → exact name → $ suffix) handles all module naming conventions.

Fixpoint: 1,428 functions. QSpec: 247/248 → 248/248 (qzi_roundtrip_spec now passes — new self-hosted/shared/qzi.qz module with serialize/deserialize/hash/filter, 14 tests).

Phase E2B: E.2 Blocker Fixes — COMPLETE

5 blockers investigated, 3 fixed, 2 verified as non-issues. Net +8 test improvement (234/242 → 242/243 in e2-blockers branch; 246/248 after merge with CMF on trunk).

Blocker	Description	Fix	Status
B5	Option/Result lack UFCS methods (`.unwrap()`, `.is_ok()`, `.is_none()`, `.unwrap_err()`, `.is_err()`, `.unwrap_or()`, `.is_some()`)	Added `extend Option` and `extend Result` blocks in `std/prelude.qz` (+42 lines)	FIXED
B3	`@derive(Eq, Hash)` collides with `## doc comments` — regular comments trigger “unknown derive trait” errors	Parser writes `@derive:Eq,Hash` (prefixed) to doc slot; `derive.qz` only processes entries with that prefix	FIXED
B1	`.size` on builtin return values (e.g., `str_split().size`) doesn’t resolve in MIR	Added `mir_intrinsic_return_type()` mapping 30+ builtins to their return types; wired into `mir_infer_expr_type` and NODE_LET handler	FIXED
B4	String interpolation `#{}` not working	Already fully implemented in self-hosted parser at `parser.qz:858-915`. Tested and confirmed working	NON-ISSUE
B2	`Vec<UserStruct>` field access broken	Works correctly — push(), .size, and field access on elements all resolve properly	NON-ISSUE

Files changed: std/prelude.qz (+42), self-hosted/frontend/parser.qz (+1/-1), self-hosted/frontend/derive.qz (+10), self-hosted/backend/mir.qz (+53).

QSpec: 246/248 (qzi_roundtrip_spec pre-existing + tco_spec subprocess env).

Phase 11 Regression Fix — COMPLETE

After merging three Phase 11 branches (task_group, generics, constant-dedup), 4 test regressions appeared. Fixed in two targeted changes:

Root Cause	Tests	Fix
Generic type stripping destroyed Vec element type info	3 (event_loop)	Removed 2 strip sites in `mir_infer_expr_type` and `mir_lower_stmt` that blanket-stripped `<T>` from return types. Added 3 targeted strips at actual struct registry lookup sites (NODE_FIELD_ACCESS in `mir_lower_expr`, NODE_FIELD_ACCESS in `mir_infer_expr_type`, NODE_FIELD_ASSIGN)
Thread pool results pointer race with realloc	1 (thread_pool 64-task)	Moved capacity check + realloc inside pool mutex in `taskgroup_spawn`. Worker and await-all now lock mutex to read results pointer and store result after task execution, preventing use-after-free when main thread reallocs

Key insight: Caching the results pointer before mutex unlock was insufficient — the main thread could realloc between the worker’s unlock and its eventual store. The correct fix is re-acquiring the mutex when storing results.

Parallel Track A: Closure Spawn + CAS Ring Buffer — COMPLETE

Track	Description	Tests	Status
Closure spawn typecheck fix	`spawn (-> expr)` lambda type unwrapped to Int in typecheck.qz	+3	DONE
CAS-safe ring buffer	`rb_push_cas`/`rb_pop_cas` with `atomic_cas` for MPMC contention	+3	DONE
is_cancelled outside task_group	`is_cancelled()` works via `@__qz_cancel_ptr`	+1	DONE
Total		+7

Compiler change (typecheck.qz): In tc_expr NODE_SPAWN handler, when spawn expression is NODE_LAMBDA, override expr_type from Function to TYPE_INT. This fixes “expected Int but got Function” on await h for closure spawns.

Parallel Track B: SSA Naming + Private Visibility — COMPLETE

Track	Description	Tests	Status
SSA v-var naming fix	`cg_sanitize_var_name` renames `v1`/`v2`/… to `_u.v1`/…	+5	DONE
Private struct/enum visibility	`tc_lookup_struct`/`tc_lookup_enum` skip `$$` prefixed names	+4	DONE
Cross-module extend method	Multi-file extend with module-internal helper	+1	DONE
Total		+10

Compiler changes:

codegen.qz: cg_sanitize_var_name() detects v + all-digits patterns and prefixes with _u. to prevent SSA collisions. Applied at alloca, load, store, addr_of, and param store sites.
typecheck.qz: tc_lookup_struct/tc_lookup_enum skip struct/enum names containing $$ (private namespace marker).
Fixture files: priv keyword changed to private (correct syntax).

Parallel Track C: Rust-Style Diagnostic Engine — COMPLETE

Track	Description	Tests	Status
`diagnostic.qz`	New module: colored Rust-style error output with error codes, source context	0 (infra)	DONE
`tc_emit_diagnostics`	Categorizes errors by pattern, strips/assigns QZ codes, adds span/suggestion	0 (infra)	DONE
Total		0

New file: self-hosted/middle/diagnostic.qz (~387 lines) — diag_new, diag_set_source, diag_set_span, diag_set_suggestion, diag_emit. Emits error[QZ0201]: Type mismatch with source context, underline caret, and color-coded output. Error code categorization: QZ02xx (type), QZ03xx (struct/enum), QZ04xx (function/variable).

Phase U — Union/Intersection/Record Types (P0)

Priority: P0 — BLOCKING | Intersection types are a core differentiator; incomplete codegen undermines the type system’s headline feature.

Status: Phase 8F ACTIVATED — record/union types fully live | Duration: ~10 hours

Record types { x: Int, y: String } — anonymous structural types with row polymorphism.

Phases 0-7 (COMPLETE): SimpleSub foundation in both compilers — TY_UNION/TY_INTERSECTION types, | and & type operators, subtype relations, MIR operations, LLVM emission, exhaustiveness checking, linearity propagation.

Phase 8: Row Polymorphism & Structural Subtyping

Sub-phase	Description	Status
8A	Parser record type syntax in both compilers	DONE
8B	Type resolution for record types	DONE
8C/8E	Type checker + MIR field access	DONE
8D	Row variables — InferStorage + record-aware unification	DONE
8G	Monomorphized codegen — GEP offset specialization	DONE
8H	Integration tests (3/3 pass)	DONE
8F	Intersection simplification — record `&` record → merged record	DONE — range predicates fixed, TYPE_RECORD_BASE+idx live, 5 union tests

Phase 8F Status: ACTIVATED. Root cause was overlapping type ID range predicates, not a pipeline routing issue. tc_is_newtype matched IDs >= 1000 (including union 2000+ and record 3000+), causing OOB access into newtype_names[]. Similarly tc_is_union_type matched record IDs. Fix: narrowed predicates to non-overlapping ranges (newtype 1000-1999, union 2000-2999, record 3000-3999). Now: tc_parse_type returns TYPE_RECORD_BASE+idx for { field: Type } annotations, tc_register_intersection returns the merged record type, tc_is_i64_type covers all extended ranges. 6 record tests + 5 new union tests pass. Also fixed: infer.qz TYPE_RECORD constant (51→52, was duplicating TYPE_INTERSECTION).

Key decisions:

Record type syntax: { field: Type } in type positions (no conflict with block syntax)
Row variables are implicit only — inferred from field access on untyped params
Monomorphization: concrete GEP offsets per call site (Zig/Rust style, zero-cost)
Width subtyping: struct with extra fields satisfies narrower record type

U.9: Intersection Type Completion — COMPLETE (14/14 core, 3 permanently deferred)

Complete the & type operator from infrastructure to full round-trip codegen:

Sub-phase	Description	Status
U.9.0	Registered intersection type IDs (`TYPE_INTERSECTION_BASE + index`) with interning	✅ DONE
U.9.1	`&` in function parameter types — accept intersection-typed args	✅ DONE (record intersections)
U.9.2	Record field conflict detection — conflicting field types in `{ x: Int } & { x: String }`	✅ DONE
U.9.3	Intersection subtype rules — `A & B <: A` and `C <: A & B` in `tc_is_subtype`	✅ DONE
U.9.4	Member-wise `tc_types_match` for registered intersections	✅ DONE
U.9.5	Intersection type helper functions (`tc_is_intersection_type`, `tc_intersection_members`, `tc_intersection_member_types`)	✅ DONE
U.9.6	Initial test suite — 5 intersection-specific QSpec tests	✅ DONE
U.9.7	Mixed record + trait intersections (`{ name: String } & Printable`)	✅ DONE — `tc_register_intersection` separates record/non-record parts, merges records, stores in `intersection_record_fields`/`intersection_record_types`
U.9.8	`tc_type_meet` — greatest lower bound computation	✅ DONE
U.9.9	Impossible intersection errors (`Int & String` → QZ0150 + TYPE_NEVER)	✅ DONE
U.9.10	Generic intersection constraints — multi-trait bounds `T: Eq + Ord` validated at call sites	✅ DONE — positive validation + negative constraint test. Compiler hang no longer reproducible (likely fixed by F.2 monomorphization loop guard). See `docs/bugs/U9_HANG_INVESTIGATION.md`
U.9.11	Comprehensive test suite — 16 active tests (0 pending), expanded from 5	✅ DONE
U.9.12	Canonical ordering — alphabetical sort before interning ensures `A & B == B & A`	✅ DONE
U.9.13	Display names — `tc_type_name_full` renders intersections as `A & B`	✅ DONE

Exit Criteria: ~~def f(p: { x: Int } & { y: String }) fully round-trips through parse → typecheck → MIR → codegen → runtime.~~ ✅ DONE. ~~Union type narrowing works in pattern matching.~~ Permanently deferred — incompatible with existential type model (see U.9.16 rationale below).

Key bug fix (U.9.14): QZ0151 conflict detection was silently failing because untyped Vec elements were compared by pointer identity instead of string equality. Fixed with as_string() casts — { x: Int } & { x: String } now correctly emits QZ0151 error.

U.9.15 (Return position): Intersection types in function return position verified working — ps_parse_type and tc_parse_type handle & uniformly. 2 tests added.

Deferred items — detailed prerequisites and implementation paths:

U.9.10 Negative Test — Missing Trait Impl Rejection

Blocked by: Pre-existing compiler hang on trait-bounded generics. When a program has both impl Trait for Type blocks AND calls to def f<T: Trait>(x: T), the compiler enters an infinite loop (confirmed with 15s timeout). The hang is NOT in intersection type code — it’s in the monomorphization or type resolution pipeline. Prerequisites to unblock:

Isolate minimal reproduction case (a 20-line .qz file triggers it)
Profile with lldb or add eputs tracing to mir_specialize_generic_function loop
Likely fix: add a visited-set or depth limit to prevent re-specializing the same <T=ConcreteType> infinitely Estimated effort: Medium (2-4 hours). Fix is likely a one-line guard in mir.qz.

U.9.16 — Type Narrowing in Match

Blocked by: No type test pattern syntax exists. Quartz’s match patterns support enum variants (Some(x)), wildcards (_), literals, and idents — but not type tests (case x: Trait). All types erase to i64 at runtime, so there’s no runtime type information (RTTI) to dispatch on. Prerequisites to unblock:

Type test pattern syntax — add case x: TypeName => ... to parser (new pattern node, e.g. NODE_TYPE_TEST)
RTTI or trait witness values — at minimum, a tag word per value that identifies its concrete type. Without this, the compiler cannot emit runtime type checks. Alternatively, intersection narrowing could be compile-time only (like TypeScript’s CFA), but that requires data flow analysis infrastructure.
tc_expr_match update — when scrutinee is an intersection type and arm has a type test, narrow the binding’s type within the arm body scope Estimated effort: High (8-16 hours). Requires parser + typecheck + MIR + codegen changes. Could be partially implemented as compile-time-only narrowing without RTTI (lower effort, ~4 hours) but with limited utility.

U.9.17 — Distributivity Law

Should NOT be implemented naively. The rule A & (B | C) = (A & B) | (A & C) is algebraically sound for pure record and trait types (per SimpleSub/MLsub — Parreaux 2020, Dolan & Mycroft 2017), but unsound for function types with computational effects (Dunfield 2014). Since Quartz has mutable state and side effects, function type distributivity would be incorrect. Prerequisites to unblock:

Effect system or purity annotations — mark functions as pure/effectful so distributivity can be selectively applied to pure function types only
Type simplification pass — add a post-inference pass that applies distributivity rules to record/trait types (safe) and flags function types (unsafe)
tc_type_simplify function — new function in typecheck_registry.qz that normalizes intersection/union combinations Estimated effort: Very high (16+ hours). An effect system is a prerequisite. Defer until Quartz has purity annotations. Record/trait-only distributivity could be done in ~4 hours but provides minimal practical value.

U.9.18 — Vtable Dispatch for Trait Intersections — PERMANENTLY DEFERRED (Future `dyn Trait` Phase)

Decision (Feb 28, 2026): Vtable dispatch is not an intersection type feature — it’s a dynamic dispatch feature. It belongs in a future dyn Trait phase, not U.9. Intersection types are COMPLETE without it.

What it would enable: Runtime polymorphism via dyn Trait — heterogeneous collections (Vec<dyn Printable>), plugin architectures, open-ended type sets where concrete types aren’t known at compile time.

Why not now: Quartz uses monomorphization (Rust/Zig style). All generic code is specialized to concrete types at compile time. Every call site knows the exact function to call. This is correct for Quartz’s current use cases and produces faster code (direct calls, full inlining).

Who needs it: Plugin systems, GUI/widget frameworks, event handler queues, error type hierarchies, game ECS patterns — any domain where you store multiple types in one collection and dispatch uniformly. Nobody is building these in Quartz yet because the ecosystem isn’t there.

When to implement: When a concrete user need arises — someone trying to build something in Quartz and hitting the wall of “I can’t have a heterogeneous collection.” That’s the right motivating use case. Building infrastructure ahead of demand is premature.

Planned approach (Rust dyn Trait model):

Explicit opt-in — dyn Trait syntax marks dynamic dispatch. Users choose static vs dynamic per call site. Maximum control.
Fat pointer representation — @value struct DynTrait { data: Int, vtable: Int } internally. Fits within @value struct infrastructure (already implemented in M.R.5/M.R.6).
Vtable layout — global constant array of function pointers per impl Trait for Type. One vtable per (Type, Trait) pair.
Coercion codegen — concrete_value as dyn Trait packs data + vtable pointer.
Indirect call codegen — load method pointer from vtable at known offset, call through pointer.
Intersection vtables — for dyn (A & B), concatenate vtable entries from both traits. Requires canonical ordering (already implemented in U.9.12).

Estimated effort: 20-30 hours. Well-understood patterns (Rust, C++, Swift, Go all do this).

Prerequisites: None beyond current compiler state. Fat pointers fit the @value struct model. No language features need to exist first — this is self-contained when the time comes.

Phase STD — Standard Library (P0)

Priority: P0 — BLOCKING | You cannot build real software without collections, I/O, string processing, math, and serialization.

Rationale: The language currently relies on ~40 compiler intrinsics and thin std/ wrappers. There is no split(), no trim(), no Path, no Directory, no Random, no Duration. Every program needs these. This is the single largest gap between “works” and “usable.”

Approach: Build the stdlib in Quartz itself (dogfooding). Each sub-phase should be independently usable and tested. Prioritize the modules most needed by real programs.

STD.1: String Processing — COMPLETE

std/string.qz — 20 functions (split, join, trim, replace, case conversion, etc.)

String.split(delimiter: String): Vec<String> — split by delimiter
String.join(parts: Vec<String>, sep: String): String — join with separator
String.trim(): String / String.trim_left() / String.trim_right() — whitespace stripping
String.replace(old: String, new: String): String — substring replacement
String.starts_with(prefix: String): Bool / String.ends_with(suffix: String): Bool
String.to_upper(): String / String.to_lower(): String — case conversion
String.contains(sub: String): Bool — already exists via intrinsic, ensure UFCS
String.chars(): Vec<Int> — character iteration (codepoints)
Tests: string_spec.qz (subprocess-based — see closure SIGSEGV note)

STD.2: Collections — COMPLETE

6 collection modules in std/collections/:

Stack (std/collections/stack.qz) — LIFO stack wrapping Vec
Queue (std/collections/queue.qz) — FIFO queue with Vec + head pointer + compaction
Deque (std/collections/deque.qz) — ring buffer double-ended queue
PriorityQueue (std/collections/priority_queue.qz) — binary min/max heap
SortedMap (std/collections/sorted_map.qz) — ordered map via sorted arrays + binary search
LinkedList (std/collections/linked_list.qz) — array-based doubly-linked list (parallel Vecs)
Tests: 45 tests across 6 spec files (stack, queue, deque, priority_queue, sorted_map, linked_list)
sort(v: Vec<T>) / sorted(v: Vec<T>): Vec<T> — requires comparison trait
Iterator protocol (for item in deque) — requires language-level for-in desugaring

STD.3: I/O & Filesystem — COMPLETE

4 I/O modules in std/io/:

Path (std/io/path.qz) — Unix path manipulation (join, parent, filename, stem, extension, components)
File (std/io/file.qz) — FileHandle struct + convenience wrappers (read_all, write_all, read_lines, append, copy)
Stream (std/io/stream.qz) — println, eprintln, write_stdout, write_stderr, read_stdin_line
BufferedReader / BufferedWriter (std/io/buffered.qz) — buffered I/O with configurable buffer size
Tests: 29 tests across 4 spec files (path_struct, file_helpers, stream, buffered_rw)

STD.4: Math & Numeric — COMPLETE

std/math.qz — 30+ functions (abs, min/max, pow, gcd/lcm, clamp, trig, log, etc.)

STD.5: Time — COMPLETE

std/time.qz — 5 functions + Duration struct

Time.now(): Int — monotonic clock (nanoseconds)
Time.sleep(ms: Int): Void — sleep in milliseconds
Time.elapsed(start: Int) — measure elapsed time
Duration struct — nanosecond-precision time span (int64, ±292 year range)
Constructors: duration_from_secs/millis/micros/nanos, duration_zero
Accessors: duration_to_secs/millis/micros/nanos
Arithmetic: duration_add/sub/mul
Comparison: duration_cmp (-1/0/1), duration_is_zero
Tests: time_spec.qz + duration_spec.qz (15 tests)

STD.6: Serialization — COMPLETE

Hardened JSON/TOML, added CSV:

STD.7: Error Types — COMPLETE

Standard error handling infrastructure:

STD.8: Math Trig/Random/Duration — COMPLETE

Final gap-filling sprint — 6 new compiler intrinsics, 2 new stdlib modules, 1 struct:

6 new math intrinsics: f64_tan, f64_asin, f64_acos, f64_atan, f64_log2, f64_log10 — full compiler pipeline (typecheck_builtins, mir_intrinsics, codegen_intrinsics, codegen_runtime, typecheck UFCS)
Math constants: MATH_TAU, math_to_radians, math_to_degrees, 16 wrapper functions
Random module (std/random.qz): random_bool, random_shuffle (Fisher-Yates), random_choice, random_sample (partial Fisher-Yates)
Duration type (std/time.qz): Duration struct (int64 nanos), constructors, accessors, arithmetic, comparison
Tests: 35 math trig + 9 random + 15 duration = 59 tests across 3 new spec files

STD.U: Unification Pass — COMPLETE

Unified naming and higher-order methods across all collections:

Naming aliases: Queue (push/shift/first), Deque (push/pop/unshift/shift/first/last), LinkedList (same + linked_list_new), PriorityQueue (priority_queue_new/max)
Higher-order methods: each, map, filter, reduce, find, any, all, count, to_vec on Stack, Queue, Deque, LinkedList, PriorityQueue (1-arg callbacks) and SortedMap (2-arg key-value callbacks + keys()/values())
Bytes fixes: .eq() returns Bool (was Int), added .is_empty(), .to_vec()
File I/O Result migration: file_read() → Result<String, IoError>, file_write() → Result<Int, IoError> (old functions kept as unchecked variants)
Tests: 5 unified naming + 21 enumerable + 7 completion = 33 tests across 3 spec files
U.11 — COMPLETE: String UFCS compiler wiring — 7 methods promoted to full intrinsics: .is_empty(), .substr(), .trim_left(), .trim_right(), .pad_left(), .pad_right(), .chars(). Wired across 5 layers (typecheck_builtins, UFCS dispatch, mir_intrinsics, codegen_intrinsics, codegen_runtime). cg_emit_runtime_helpers_3 added. 7 new tests, 242/242 QSpec green, 1425 functions, fixpoint verified

NET: Networking & TLS — COMPLETE

Full networking standard library (NET.1-NET.6):

Key bugs fixed:

send/recv channel intrinsic collision (sendto/recvfrom workaround — Quartz channel intrinsics take precedence)
Cross-module struct field index bug (TcpListener padding — compiler uses global field-name→index map)
htons double-byte-swap on ARM64 (direct big-endian writes instead)
P.5 string boundary in tcp_read (cstr_to_string for length-prefixed model)
CInt sign-extension for SSL_read/SSL_write (i32 -1 zero-extended to i64 4294967295)
String == pointer comparison in http.qz causing infinite loop (.eq() for all string comparisons)

Exit Criteria: An HTTPS GET request to a real server works end-to-end from pure Quartz code. ✅ ACHIEVED — http_get("https://example.com") returns status 200 with full HTML body.

Exit Criteria: A program that reads a CSV file, processes strings, does math, writes output, and handles errors can be written entirely with stdlib — no C FFI required. ✅ ACHIEVED — all building blocks in place.

Phase SPEC — Formal Language Specification (P1)

Priority: P1 — IMPORTANT | Without a specification, the language is defined by “whatever the compiler does.” Independent implementations, conformance testing, and reproducibility all require a spec.

Rationale: The existing QUARTZ_REFERENCE.md is a user guide, not a specification. It describes behavior informally. For production use, we need formal syntax grammar, typing rules, and evaluation semantics that can be independently verified.

SPEC.1: Formal Syntax Grammar — COMPLETE

docs/spec/GRAMMAR.md — 19-section EBNF grammar (415 lines)

Complete EBNF grammar for all language constructs
Lexer token table (all 115+ token types)
Operator precedence and associativity table
Semicolon insertion / newline significance rules
Tests: grammar can parse all existing QSpec programs

SPEC.2: Type System Specification — COMPLETE

docs/spec/TYPE_SYSTEM.md — 13-section type system spec (550 lines)

Typing rules for Hindley-Milner inference (judgment form notation)
Structural subtyping rules (width subtyping, record types)
Union type formation and narrowing rules
Intersection type formation and merging rules
Linear / affine type rules (move, borrow, drop)
Parametric polymorphism (generalization, instantiation)
Trait constraint satisfaction rules

SPEC.3: Evaluation Semantics — COMPLETE

Expression evaluation order (left-to-right, strict) — documented in EVAL_SEMANTICS.md
Function call convention (value passing, i64 model) — documented in EVAL_SEMANTICS.md
Pattern matching semantics (exhaustiveness, binding, guards) — documented in EVAL_SEMANTICS.md
Module resolution algorithm — documented in EVAL_SEMANTICS.md
Name mangling scheme — documented in EVAL_SEMANTICS.md

SPEC.4: Memory Model Specification — COMPLETE

Ownership and move semantics rules — documented in MEMORY_MODEL.md
Borrow rules (shared, exclusive, scope-based lifetimes) — documented in MEMORY_MODEL.md
Arena allocation semantics — documented in MEMORY_MODEL.md
Drop ordering guarantees (LIFO, scope-based) — documented in MEMORY_MODEL.md

SPEC.5: Conformance Test Suite — COMPLETE

Derive executable tests from each spec rule — 108 tests (85 eval + 23 memory)
Tag tests with spec section references — conformance_eval_spec.qz + conformance_memory_spec.qz
Coverage tracking: % of spec rules with tests — all spec rules covered

Exit Criteria: An independent implementer could build a conforming Quartz compiler from the specification alone (even if not efficiently).

Phase F — Feature Completion (P1)

Priority: MEDIUM — Most feature work complete. Remaining items are deferred or blocked.

Rationale: Feature completion is largely DONE. All major feature blockers resolved through Phases 19-22, F-Delta, BC, MS. Only 4 non-safety it_pending tests remain (3 PCRE2 platform limits, 1 htons extern). 14 safety infrastructure tests pending activation (S2.P/S2.B/S2.L). Trait constraint enforcement now working (was not blocked — test expectation updated). Remaining open items below are either platform-limited or await deeper architectural changes.

F.1: Parser Completion (~13 tests)

Complete the self-hosted parser to support all documented syntax:

Curly lambda syntax { x -> expr } — DONE (Phase 10: standalone + trailing)
Standalone do..end block expressions — DONE (Phase 10: NODE_BLOCK for nullary)
#{} string interpolation inside closures — CONFIRMED WORKING (Sprint 4 confirmed, 8 interpolation tests across all closure contexts)
{key: val} shorthand hashmap — FIXED (Phase 12: emit string keys, not symbol keys)
& as bitwise AND newline continuation — FIXED (Phase 12: trailing & continues across lines)
| disambiguation (closure vs bitwise OR) — CONFIRMED CLEAN (lexer cleanly separates |/||/|>)
<< / >> shift operator newline continuation — FIXED (Phase 12: trailing <</>> continues across lines)
Fn(Int): Int as struct field type — FIXED (Phase F-Delta: typechecker rewrites to FIELD_ACCESS callee, MIR emits indirect call)

Metric: All parser limitation entries in QSpec status section resolved or explicitly documented as intentional.

F.2: Generic Types & Functions (~14 tests) — COMPLETE

Generic type system gaps fully resolved:

F.3: Trait System Completion (~3 tests remaining)

Finish the trait system from “basic dispatch works” to “full-featured”:

Trait inheritance — trait Ordered: Eq — DONE (Phase 15: super-trait enforcement in typecheck.qz)
Where clause syntax — where T: Trait — DONE (Phase 15 Stream B: parser.qz)
Default method inheritance — DONE (Phase 9: partial impl inherits defaults)
Standard traits library — DONE (Phase 10: Eq, Ord, Hash, Show, Clone all work via subprocess)
Cross-module trait impl visibility — DONE (Phase 10: both impls coexisting)
@derive attribute — DONE (Phase F.3: derive.qz, 5 traits, typed params, 15 tests)
Multi-trait bounds (T: A + B) — DONE (Phase 10)
Self type in trait methods — DONE (Phase 10)
Generic impl blocks — DONE (Phase 10)

F.4: Concurrency (~4 tests remaining)

Fix broken concurrency features and complete the threading model:

task_group end-to-end — DONE (Phase 11: fixed needs_closure_wrapper + removed thread_local for lli)
thread_pool — DONE (Phase 11: nested groups, parallel_map, 64 tasks, side effects)
recv_timeout — DONE (Phase 11: clock_gettime works via lli)
Closure spawn (spawn (-> expr)) — FIXED (Parallel Track A: lambda type unwrapped to Int)
g.spawn(-> expr) UFCS syntax — FIXED (Phase F Reset: ps_is_method_name_token accepts keyword tokens >= TOK_SPAWN after ./?.)
is_cancelled() outside task_group — FIXED (Parallel Track A)
Task<T> return value extraction — ALREADY DONE (F-Beta: tc_make_ptype + tc_ptype_arg1 for await, codegen stores at offset 8)
Cooperative cancellation (check-and-bail pattern) — DONE (cancel_token_free builtin added, 18 subprocess tests in cancel_token_spec.qz: token lifecycle, check-and-bail loops, task_group integration via atomics, cross-thread sharing, defer+cancel cleanup, edge cases). Deferred: hierarchical tokens (requires linked data structure), timeout tokens (users can spawn + sleep_ms + cancel), is_cancelled() without task_group MIR flag (orthogonal fix)
Fix multi-level closure capture for threaded contexts — FIXED (mir_ctx_bind_var in lambda capture loading loop)

F.5: User Macros (~22 tests) — COMPLETE (Phase 18)

User macro system implemented:

Quote/unquote macro expansion — DONE (Phase 18: clone_with_unquote AST cloning)
String template macro expansion — DONE (Phase 18: ast_to_source + re_parse_expr)
Macro registry + two-phase expansion — DONE (Phase 18: collect defs, expand calls, remove defs)
Variadic parameters (values...) — DONE (Phase 18: parser support + validation)
Hygiene — macro-introduced bindings don’t leak — DONE (Phase 18: per-expansion context)
@derive implemented via macro expansion — DONE (Phase F.3: source gen + re-parse at Phase 2.4)
$debug(expr) — DONE (Phase 15: already working as built-in macro)
Basic pattern matching on AST fragments — DONE (fragment specifiers: expr, ident, type, block, tt parsed in ps_parse_macro_def, validated in validate_macro_fragments. Stored in param node op field. 6 tests in macro_fragment_spec.qz)

F.6: Regex (~61 tests — 57 activated in Phases 16+17, 4 remaining)

Complete regex support:

~r regex literal MIR lowering (Phase 17: NODE_REGEX_LIT handler)
Lexer regex pattern extraction (Phase 17: strip ~r"..." wrapper)
=~ match operator end-to-end (Phase 17)
!~ non-match operator end-to-end (Phase 17)
=~? capture operator with Vec extraction (Phase 17)
POSIX regex linking at runtime via lli (regcomp/regexec resolve dynamically)
Named capture groups (basic support exists in C bootstrap)
Match with regex arms — DONE (Phase 22: parser TOK_REGEX in ps_parse_pattern + MIR regex pattern case)
PCRE2 functions in lli (regex_split, regex_find_all blocked — PCRE2 not available in lli)

F.7: Remaining Blockers (~100+ tests)

Clear small-batch blockers:

Arena safety analysis — DONE (Arena Safety Analysis: compile-error warnings, 4 tests activated)
Multi-file / import edge cases — DONE (Phases 19-21: directory modules, generic enum return, global vars, re-export filtering)
Record types — DONE (Phase 19: parser & after }, TYPE_RECORD in tc_parse_type, global field fallback)
Safe navigation ?. — DONE (Phase 19: lexer fix, MIR OP_EQ fix, TYPE_OPTION registration, global field search)
Mutable borrows — DONE (Phase 19 + Phase BC: full borrow checker with QZ1205-1211, ephemeral release, mutation prevention, dangling ref prevention)
Slice intrinsics — DONE (Phase 15 Stream B: slice/slice_get/slice_set/slice_len/str_slice)
field_offset intrinsic — DONE (Phase 15 Stream B: @repr(C) struct field offsets)
Fn in struct field — FIXED (Phase F-Delta: Fn-typed field calls via dot syntax, FIELD_ACCESS callee handler + indirect call)
@repr(C) struct type declaration — DONE (Phase 22: packed struct codegen + combined @cfg+@repr(C))

Exit Criteria: it_pending count drops to <30. STATUS: ACHIEVED — currently 4 QSpec pending (3 PCRE2 platform limits, 1 htons extern). All feature blockers resolved.

F.8: Cross-Module String `+` Operator — FIXED

Problem: The + operator silently fell back to integer addition when the MIR layer couldn’t heuristically determine that both operands were strings. This happened reliably when either operand was a cross-module function call return value (e.g., color_red("error: ") + msg), because mir_is_string_expr() used a hardcoded heuristic checker that missed cross-module function return types.

Fix: Added a 6-line universal fallback at the end of mir_is_string_expr() in mir_lower.qz that calls mir$mir_infer_expr_type() — the existing MIR type inference engine which correctly resolves function return types across module boundaries. When all heuristic checks fail, this fallback checks if the inferred type equals “String” and returns 1. Zero changes needed to the type checker.

Audit mir_is_string_expr() — identified hardcoded heuristic list (14 known intrinsics) + incomplete user function lookup
Add mir_infer_expr_type() universal fallback — 6 lines in mir_lower.qz
QSpec tests: 4 cross-module string + patterns verified (string_plus_cross_module_spec.qz)
Full regression: 284/284 QSpec files pass, zero breakage
Audit and simplify .concat() usage in stdlib that exists only as a workaround (tracked, low priority)

F.9: Quartz Linter — Block Balance Checking — COMPLETE

Rewrote check_balance() with four enhancements: (1) else if implicit nesting tracking, (2) string literal skipping with backslash-escape handling, (3) line comment skipping, (4) per-construct line-number error reporting. Added check_extra_ends() for too-many-ends detection. Modernized to current stdlib conventions. 24 tests in lint_balance_spec.qz.

Enhance check_balance() to track else if as implicit if nesting
Add string literal and comment skipping
Report specific line numbers for mismatches
Modernize tools/lint.qz to current Quartz stdlib conventions
Integrate into quake format_check or pre-commit hook for automated checking

F.10: UFCS on Top-Level Constants — COMPLETE

Root cause: Parser treats Uppercase.method() as associated function syntax (Name$method), dropping the receiver from args. For type names (e.g., Point.origin()), this is correct. For uppercase variables/constants (e.g., GREETING.concat()), it’s wrong.

Fix: Typechecker fallback in typecheck_walk.qz — when Name$method fails to resolve and Name is a bound variable in scope, rewrite the AST to UFCS (prepend receiver, set is_ufcs flag) and recurse through existing dispatch. Associated functions (Type.method()) are unaffected since they resolve on the first attempt.

Fix typechecker to recognize uppercase constants and dispatch UFCS correctly
Add QSpec test: 9 tests in ufcs_constants_spec.qz — .concat(), .find(), .size, .slice(), .starts_with(), .eq() on String constants; uppercase/PascalCase locals; associated function regression

Phase X — Compiler Architecture Cleanup (P2)

Priority: P2 — DESIRABLE | Structural debt is the ceiling on all future work, but most critical items (X.1, X.2, X.4) are already done.

Rationale: The compiler works, but its structure — large files, 61-field god objects, and triplicated constants — makes every change risky. This phase refactors without changing behavior, validated by fixpoint. (X.2 decomposition and X.4 intrinsic dispatch refactor have significantly improved this.)

X.1: Constant Deduplication — COMPLETE

Eliminated three-way constant divergence across the compiler. 14 files changed, net -439 lines:

Deduplicate OP_* constants (30 dups) via op_constants$ qualified access — DONE
Deduplicate NODE_* constants (164 dups) from ast_print.qz, typecheck_util.qz, mir.qz — updated ~440 refs to node_constants$ — DONE
Create shared/type_constants.qz (55 constants + PTYPE_BASE) — removed defs from typecheck_util.qz, updated 4 consumer files + mir.qz TC_TYPE_* bridging — DONE
Fix infer.qz TYPE_RECORD constant divergence (51→52) — DONE (Phase 22)

Fixpoint: 1357 functions, 212/214 QSpec (same 2 pre-existing).

X.2: File Decomposition — COMPLETE

Split three monolithic compiler files into 11 semantic modules:

File	Before	After	New Modules
`codegen.qz`	12,549	1,744 (86% smaller)	`codegen_util.qz` (666), `codegen_intrinsics.qz` (8,033), `codegen_runtime.qz` (2,145)
`typecheck.qz`	10,395	7,016 (32% smaller)	`typecheck_util.qz` (1,292), `typecheck_builtins.qz` (787), `typecheck_registry.qz` (1,328)
`mir.qz`	9,368	8,239 (12% smaller)	`mir_intrinsics.qz` (533), `mir_const.qz` (627)

All imports form a DAG (no cycles). Mutual recursion clusters (tc_expr/tc_stmt, mir_lower_expr/mir_lower_stmt) stay in core files. quartz.qz unchanged — all 15 public API functions remain in core. Fixpoint validated: 1262 functions, gen2 == gen1, 199/199 QSpec pass.

Key decisions:

Diamond import fix: LookupResult extend block stays in typecheck_util.qz; wrapper functions in typecheck.qz for quartz.qz compatibility
mir_const.qz mirrors NODE_/OP_ constants locally (can’t import mir — circular dependency)
codegen_intrinsics.qz is the largest file (~8,000 lines) — intrinsic dispatch refactored to two-level HashMap in Phase X.4

X.3: God Object Refactoring — COMPLETE

Decomposed god objects into cohesive sub-structs (MAX_PARAMS now 128):

TcErrors (6 fields) — errors/warnings + lines/cols, absorbed 3 module globals
TcScope (10 fields) — binding management + scope/return type tracking
TcSafety (15 fields) — borrow/linear/move states, absorbed 9 module globals
TcRegistry (41 fields) — struct/enum/func/trait/impl registries, absorbed 9 module globals
TypecheckState core: 17 fields (4 sub-structs + 13 core), down from 64
MirDropState (4 fields) — drop_types, droppable_stack, defer_stack, loop_defer_depth
MirGenericState (5 fields) — generic_bounded_funcs, pending_specs, spec_param_types, spec_current_type, impl_current_type
MirContext core: 27 fields (2 sub-structs + 25 core), down from 34
Fixpoint verified: 1364 functions, 210/214 QSpec

Discovery (resolved): C bootstrap chained field assignment bug found and fixed — see X.5 below.

X.4: Dispatch Table Architecture — COMPLETE

Replace string-matching chains with registration-based dispatch:

Intrinsic dispatch — DONE (Phase X.4: two-level HashMap, 388 handlers across 16 categories, O(1) category lookup)
tc_expr dispatch extraction — DONE (7 handler functions extracted, tc_expr 2,296→506 lines, 78% reduction):
- tc_expr_call (~1,036 lines) — NODE_CALL, NODE_CALL_INDIRECT
- tc_expr_field_access (~240 lines) — NODE_FIELD_ACCESS, NODE_SAFE_NAV
- tc_expr_try (~200 lines) — NODE_TRY_EXPR
- tc_expr_match (~100 lines) — NODE_MATCH
- tc_expr_struct_init (~76 lines) — NODE_STRUCT_INIT
- tc_expr_lambda (~79 lines) — NODE_LAMBDA
- tc_expr_index (~80 lines) — NODE_INDEX
mir_lower_expr dispatch extraction — DONE (Phase X.4-d: 2,446→660 lines, 73% reduction, 8 category handlers: call, binary, match, concurrency, collection, lambda, alloc, try)
cg_emit_instr dispatch extraction — DONE (Phase X.4-d: 960→285 lines, 70% reduction, 4 category handlers: call_ops, binary, index_ops, memory_ops)
Type kind dispatch — eliminate long match/if chains on type constants (future nice-to-have)

Exit Criteria: No file > 3,000 lines (partially achieved — codegen core 1,744, typecheck core ~5,900, mir core 8,239). No struct > 20 fields (achieved: TypecheckState 17, MirContext 27). Intrinsic dispatch chains eliminated ✅. tc_expr dispatch extracted ✅. mir_lower_expr extracted ✅. cg_emit_instr extracted ✅. Type kind dispatch remains as future nice-to-have.

X.5: C Bootstrap Bug Fixes — COMPLETE (see X.5b for remaining gaps)

Chained field assignment — DONE. Root cause was in the parser (not codegen): a.b.c = val was parsed as a.b = val. Fixed + removed 7 local-variable workarounds in mir.qz. QSpec: 210/214.
Chained field index-assign — a.b.items[i] = val — works in self-hosted compiler (no hardcoded limits)
Nested struct literal in struct literal — Outer { inner: Inner { x: 1 } } — works in self-hosted compiler
Closure SIGSEGV with large imports — RESOLVED by architecture. Root cause: C bootstrap MAX_LOCALS (640) overflow. Self-hosted compiler uses dynamic Vec-based variable tracking. No reproduction possible with self-hosted compiler. C bootstrap retired.

X.5b: C Bootstrap Type System Gaps — RESOLVED (C bootstrap retired Feb 2026)

Discovered during P.2 incremental compilation implementation. These limitations were specific to the C bootstrap compiler, which was retired in Feb 2026 when full self-hosting was achieved. All gaps are now moot.

eprint/eputs compile to no-ops — RESOLVED (C bootstrap retired) — Self-hosted compiler has full stderr support.
No int_to_str built-in — RESOLVED (C bootstrap retired) — Self-hosted compiler has str_from_int, string interpolation #{}, and int_to_s.
Vec<UserStruct> field access unsupported — RESOLVED (C bootstrap retired) — Self-hosted compiler handles Vec of user structs.
Typed global variable declarations unsupported — RESOLVED (C bootstrap retired) — Self-hosted compiler supports typed globals via ps_parse_global_var.

Impact: All gaps eliminated by C bootstrap retirement. The self-hosted compiler is now the sole compiler with full type system support.

X.6: String Ergonomics — COMPLETE

+= compound assignment for String — already works via parser desugaring to ast_assign + ast_binary(OP_ADD) and MIR string-aware str_concat emission. 5 QSpec tests added.
Indentation-stripped triple-quoted strings — closing """ position defines baseline; content lines have that many leading spaces stripped. lex_strip_indent helper in lexer.qz. 6 QSpec tests added.
Migrated 6 QSpec safety test files (~310 src.concat() calls → heredocs): nll_liveness, move_semantics, lifetime, multi_level_borrow, mutable_borrows, partial_moves.
X.6.1: Comprehensive heredoc migration — 14 additional QSpec files, 341 str_concat calls → heredocs. All source-building helpers inlined directly into test assertions. Files: arena_blocks, concurrency, packed_structs, fixed_width_integers, global_var, functions, traits, tco, void_match_arm, arrow_lambdas, match_exhaustiveness, conditional_compilation, regex_advanced, tuples.

X.7: Fixpoint Parity & Cache Bug — COMPLETE

Goal: Achieve perfect repeatable fixpoint with the self-hosted binary as the sole compiler. Retire the C bootstrap entirely.

Root cause: Module-level const-by-default string globals (e.g., QUARTZ_VERSION = "5.12.15-alpha") were never initialized at runtime. The MIR const evaluator (mir_const_eval_full) has no NODE_STRING_LIT handler, so it returns 0 (null). The codegen fallback that handles string global inits in __qz_module_init was skipped when MIR already synthesized that function for complex var globals. Result: QUARTZ_VERSION was null at runtime, causing strlen(NULL) crash in content_hash_combine when the cache system accessed it.

Fix (commit 61f7d56):

PASS 0.8: Extract string values from NODE_STRING_LIT const inits into prog.global_str_inits. Route non-evaluable non-string consts to global_init_nodes for runtime expression lowering.
PASS 1.5: After emitting complex var global inits in __qz_module_init, also emit mir_emit_const_string + mir_emit_store_var for any program global with a non-empty str_init. Create __qz_module_init if either complex inits OR string inits are needed.
Verified: gen1==gen2 fixpoint (both with and without cache), 1,439 functions
QSpec 274/275, zero regressions
Gen1 binary installed as self-hosted/bin/quartz

Remaining: Replace shipping binary with optimized release build, full rake test validation, retire C bootstrap dependency.

Phase M — Memory Model Evolution — SUBSTANTIALLY COMPLETE (P2)

Priority: P2 — DESIRABLE | The i64-everywhere model is the deepest architectural limitation, but core optimizations (width-aware Vec, @value, bounds-check elision) are already landed.

Rationale: Every value being i64 means structs can’t be stack-allocated, generic type parameters can’t specialize data layout, and runtime type confusion bugs are silent. This is the performance ceiling and safety ceiling simultaneously.

Status (Feb 23, 2026): Design study complete. Three implementation phases landed: width-aware Vec storage (Phase 1), @value struct stack allocation (Phase 2), bounds-check elision via selective monomorphization (Phase 3). Sieve benchmark updated to Vec. 82+ new tests across 3 spec files.

M.1: Design Study — COMPLETE

Quantify the cost: benchmark struct-heavy programs — sieve 4.7× C (i64 cache blowout), fibonacci 1.0× C (scalar optimized away)
Study Zig’s comptime type erasure — Approach 2A in design doc
Study Rust’s monomorphization — Approach 2B in design doc
Study Vale’s generational references — Approach 2C in design doc (deferred: solves different problem)
Design document: docs/design/MEMORY_MODEL_V2.md — chose hybrid 2A + selective 2B
Decide: gradual migration (keep i64 as fallback, opt-in annotations)

M.P1: Width-Aware Vec Storage — COMPLETE

Collection element width specialization (Design Study Phase 1):

elem_width.qz shared module — maps type names to byte widths and LLVM IR types
Vec<U8> → byte-width backing array (1 byte per element instead of 8)
Vec<I16>/Vec<U16> → 2-byte-width, Vec<I32>/Vec<U32> → 4-byte-width
Width-aware vec_push/vec_get/vec_set codegen
Width-aware index assign (v[i] = val)
vec_new_filled<T> intrinsic for bulk collection init
Sieve benchmark updated to Vec — closes the 4.7× C gap
27+ tests in vec_narrow_storage_spec.qz

M.P2: @value Struct Stack Allocation — COMPLETE

Value types for small structs (Design Study Phase 2):

@value annotation on structs → stack-allocated, passed by value
Narrow struct fields: U8/I8/U16/I16/U32/I32 stored at natural width
Mixed-width structs: struct Pixel { r: U8, g: U8, b: U8, a: U8 }
Nested narrow structs
30+ tests in narrow_struct_fields_spec.qz
25 tests in sized_storage_spec.qz (I8/I16/I32/U8/U16/U32 params, returns, cross-width conversion)

M.P3: Selective Monomorphization + Bounds-Check Elision — COMPLETE

Selective monomorphization for hot paths (Design Study Phase 3):

MIR_VEC_DATA_PTR — extract raw data pointer from Vec header
MIR_INDEX_RAW — bounds-check-free element load
MIR_INDEX_STORE_RAW — bounds-check-free element store
Bounds-check elision for Vec access in counted loops
LLVM codegen for all three new MIR instructions

M.R.1: Remove f32_vec_* Intrinsics — COMPLETE

Generic Vec<F32> codegen path replaces all special-case f32_vec_* intrinsics. Extended mir_is_float_expr for vec_get/vec_get_unchecked with F32/F64 annotations. RSpec integration tests migrated.

M.R.3: Enum Discriminant Sizing — COMPLETE

Simple enums (≤256 variants, no payloads) use 1-byte storage in Vec. mir_prog_enum_variant_count, mir_prog_enum_has_payloads in MirProgram. Codegen: trunc i64→i8 on push, zext i8→i64 on get. 8 tests in enum_discriminant_spec.qz.

M.R.5: Vec Inline Struct Storage — COMPLETE

@value structs stored inline in Vec. elem_width = field_count * 8; fields stored contiguously in the data array. vec_get/vec_get_unchecked return direct pointers into the Vec data (no alloca/memcpy copy) — this avoids dynamic alloca stack overflow in loops with 100K+ iterations. vec_push/vec_set use runtime elem_width from Vec header[3] to handle UFCS calls where _elem_type isn’t propagated. 7 tests in inline_struct_vec_spec.qz (value semantics test deferred — would need entry-block alloca hoisting). struct_heavy benchmark: 4.47x → 6x (inline storage eliminates boxing; remaining gap from struct creation malloc).

M.R.2: Escape Analysis for @value Structs — COMPLETE

Per-function MIR escape analysis pass detects @value struct allocations that flow to return, heap struct fields, closure captures, or globals. Escaped MIR_ALLOC_STACK registers heap-promoted via malloc(N*8) instead of alloca. Forward data-flow tracks register origins through variable bindings with transitive propagation for nested @value structs. Non-escaping structs remain stack-allocated. 11 tests in escape_analysis_spec.qz (was 6+4 pending). Fixpoint verified. Build: 1481 functions.

M.R.6: Register Passing for @value Structs — COMPLETE

Codegen-only optimization: @value struct params (1-3 i64 fields, no narrow/generic fields) decomposed into individual register arguments at LLVM IR level. Pre-scan excludes MIR_FUNC_REF targets from ABI changes. Total expanded param count capped at ≤8. Callee reconstructs struct via alloca+GEP+store. Tail calls disabled for decomposed calls. 10 tests in register_passing_spec.qz. Build: 1479 functions.

M.R.7: Bool as Narrow Type — COMPLETE

Already implemented as part of M.R.1 elem_width infrastructure. TYPE_BOOL = 2 in type_constants.qz. elem_byte_width("Bool") = 1 and elem_llvm_type("Bool") = "i8" in elem_width.qz. Vec uses 1-byte storage. Comparisons produce i1, zext to i64 for value semantics. 14 tests in bool_narrowing_spec.qz.

M.R.8: Stack Allocation for @value Struct Returns — COMPLETE

Non-escaping @value struct returns use alloca instead of malloc when --stack-alloc flag is passed. Functions returning @value structs that are (a) not recursive, (b) not func_ref targets, and (c) not in separate compilation mode get alwaysinline attribute + return-escape suppression. After LLVM opt -O2, struct constructors inline into callers → SROA promotes allocas to registers → zero-malloc struct creation. Guards exclude recursion and indirect calls (where LLVM cannot honor alwaysinline). Gated behind --stack-alloc CLI flag because the optimization requires LLVM opt -O1+ to be safe (without optimization, alwaysinline + stack alloca = dangling pointer UB). Non-escaped local struct allocas are always hoisted to the LLVM entry block (static alloca) regardless of the flag. 4 files: mir.qz (mir_func_returns_value_struct helper + suppress_return_escape param), codegen.qz (wiring + attribute emission + alloca hoisting), codegen_util.qz (stack_alloc state field), quartz.qz (CLI flag). 7 tests in stack_alloc_return_spec.qz. struct_heavy benchmark: 6x → 1.0x (C parity). Memory: 167MB → 3.8MB (vs C 3.7MB). Fixpoint verified (compiler has no @value structs → zero bootstrap risk).

Monomorphization Hardening — COMPLETE

Six improvements to the generic specialization pipeline: P1 HashMap-based specialization memoization (O(1) dedup, replaces O(n) visited set). P2 ~~Enhanced type inference for NODE_BINARY~~ (reverted — caused false positives in mir_is_string_expr fallback path, same class of bug as X.8). NODE_INT_LIT → “Int” and NODE_STRING_LIT → “String” handlers kept. P3 Polymorphization — PASS 0.9 skips bounded generic registration if body has no UFCS calls (identical code regardless of T in existential model). P5 Multi-param hardening — arity+1 self fallback for UFCS dispatch, empty-type filtering in spec name construction. P6 LLVM MergeFunctions — opt --passes=mergefunc in release builds deduplicates identical monomorphized function bodies. Cycle detection — in-progress stack prevents infinite recursion in cascading specializations. Fixpoint verified.

M.R: Remaining Work

Escape analysis — heap-promote @value structs that outlive their scope ✅ (M.R.2)
Stack allocation for non-escaping @value struct creation sites ✅ (M.R.8)

Exit Criteria: @value structs stack-allocated ✅. Vec width specialization ✅. Vec<F32> generic codegen ✅. Enum discriminant sizing ✅. Vec<Point> inline structs ✅. Register passing ✅. ~~Bool as i1~~ ✅ (M.R.1). Escape analysis ✅ (M.R.2). M.R.8 ✅.

Phase S2 — Safety Completion (P0)

Priority: P0 — BLOCKING | Core safety features work; lifetime inference completion is required for production safety claims.

Rationale: Linear types, borrows (QZ1205-1211), and move semantics (QZ1212-1216) all work end-to-end. S2.1-S2.3 COMPLETE. Multi-level borrow chains DONE (5/5 tests pass). Partial move wiring DONE (QZ1216). Match arm move tracking DONE (STR2-5). For-loop + if-expression move tracking DONE. Safety audit identified 15 holes, 3 fixed, 12 documented below. Remaining: 12 audit holes (4 MEDIUM, 8 LOW) and cross-function lifetime inference.

S2.1: Fix Core Drop Semantics

Nested field drops — DONE (Phase 14 SSA fix + 4 tests)
Deeply nested drops — DONE (recursive traversal + 1 test)
defer + Drop interaction — DONE (Block A: implicit return, $try error path, break/continue)
Drop on break/continue — DONE (Block A: drops + defers via emit_deferred_to_depth + loop_defer_depth tracking)
Drop through match arms — DONE (Wave 1: emit_and_pop_drops_for_scope at 4 match arm sites, mir_pop_drops_for_scope for return/break arms, 7 new tests)
Implicit return drops — DONE (Block A: emit_drops_for_scope(ctx, 0) before implicit TERM_RETURN)
Reassignment drops — DONE (Block A: drop old value before mir_emit_store_var in NodeAssign)
Function parameter drops — DONE (Block A: push_droppable for droppable params in mir_lower_function)

S2.2: Fix Borrow Checker — COMPLETE (Phase BC)

&mut exclusive borrow — QZ1205 double exclusive, QZ1206 conflicting, QZ1208 immutable binding — DONE (Phase 19)
Shared borrow & — prevent mutation while borrow is live — DONE (Phase BC: QZ1209 at 5 assignment paths)
Borrow scope tracking — borrows expire at end of enclosing scope, ephemeral release after calls — DONE (Phase BC: shared + exclusive ephemeral release)
Error messages — “QZ1209: Cannot mutate ‘x’ while it is borrowed” with --explain docs — DONE (Phase BC)
Dangling reference prevention — QZ1210 return borrow of local, QZ1211 store borrow in struct — DONE (Phase BC)
Borrow release on reassignment — old borrow released when holder is reassigned — DONE (Phase BC)
Multi-level borrow tracking — DONE (tc_propagate_borrow_chain, max depth 10, 5/5 S2.B tests pass)

S2.3: Move Semantics — COMPLETE (Phase MS)

S2.4: Lifetime Inference — PARTIAL (P0 Critical Path)

[!IMPORTANT] Design Principle: Ephemeral References. References (&T, &mut T) are ephemeral borrows — they exist in function scopes and call arguments, never in data structures. This is a conscious, permanent design decision. Quartz will never have Rust-style lifetime annotations ('a, 'b). References are not first-class values that can be stored arbitrarily; they are compile-time-checked aliases that prevent unnecessary copies during function calls. This gives Quartz compile-time borrow safety without the annotation burden that makes Rust’s learning curve steep.

What this means concretely:

struct S { r: &T } → compile error (QZ1211). Store a copy, a handle, a CPtr, or use @heap.

fn foo(x: &T) -> &T → safe without annotation. Returned borrow must originate from a caller-owned argument.

&local_var inside a loop → checked automatically. Borrow cannot escape the loop scope.

No 'a syntax. No lifetime parameters on structs. No lifetime bounds on generics. Ever.

Expand from scope-based tracking to NLL-lite (Non-Lexical Lifetimes without explicit annotations):

S2.4.1: Return-position borrow of local — QZ1210 prevents returning & of a local variable — DONE (Phase BC)
S2.4.2: Scope-based dangling reference detection — QZ1218 depth check at creation + scope exit validation — DONE (Phase S2.L, 5 pending tests)
S2.4.3: Cross-function borrow propagation — var r = &x; return r detected as QZ1210 (pre-NLL snapshot preserves borrow metadata through last-use release); borrow tracking on NODE_LET reassignment and NODE_ASSIGN paths — DONE
S2.4.4: Struct-stored borrows — indirect borrows via bindings detected (var r = &x; S { f: r } → QZ1211); pre-NLL snapshot captures borrow sources before tc_expr — DONE
S2.4.5: Loop-carried borrows — borrow state snapshot/restore around NODE_WHILE body; selective restore only reverts loop-created borrows, preserving NLL releases — DONE
S2.4.6: Generic lifetime error messages — dual-span diagnostics: QZ1209/QZ1210/QZ1218 now include borrow creation line; binding_borrow_lines/binding_borrow_cols fields in TcSafety — DONE
S2.4.7: Borrow narrowing — borrows expire when no longer used (NLL-lite), not at end of enclosing block — DONE (Phase NLL: liveness pre-pass in liveness.qz, use-based release in typecheck, 12 NLL tests, enhanced QZ1209 diagnostics)
S2.4.8: Activate pending safety tests — DONE (14 tests activated: 4 partial moves, 5 multi-level borrows, 5 lifetime). 8/14 pass, 6 converted to it_pending awaiting infrastructure wiring:
- S2.B (multi-level borrows): 5/5 pass — borrow chain propagation works correctly
- S2.L (lifetime): 5/5 pass — all lifetime tests active (cross-scope QZ1218, borrow chain propagation, dangling borrow at scope exit)
- S2.P (partial moves): 1/4 pass — success case works; 3 converted to it_pending (QZ1216 field-level move tracking not yet implemented)
- Newtype dogfood: 3/3 tests pass ✅ — Vec element enforcement and cross-newtype rejection verified

[!NOTE] Design Decision: NLL-lite chosen and implemented (S2.4.7). Borrows expire at last use via AST liveness pre-pass (liveness.qz). No explicit lifetime annotations needed. Conservative loop handling (double-walk fixpoint). Explicit lifetime syntax ('a annotations) permanently rejected — Quartz’s ephemeral reference model makes them unnecessary. References are scoped aliases, not storable first-class values.

Exit Criteria: ~~All 8 blocked drop/linear tests pass.~~ ✅ All original blockers resolved. ~~&mut works.~~ ✅ DONE (Phase BC). ~~Use-after-move is a compile error.~~ ✅ DONE (Phase MS: QZ1212). ~~All S2.B/S2.L/S2.P pending tests activated.~~ ✅ DONE (14 tests, 8 pass). ~~Cross-function borrows tracked.~~ ✅ DONE (S2.4.3). ~~Struct-stored borrows validated.~~ ✅ DONE (S2.4.4). ~~Loop-carried borrows validated.~~ ✅ DONE (S2.4.5). ~~Dual-span diagnostics.~~ ✅ DONE (S2.4.6). ~~Partial move wiring.~~ ✅ DONE (S24: QZ1216 field-level). ~~Match arm move tracking.~~ ✅ DONE (S24: STR2-5). ~~Remaining: 12 safety audit holes.~~ ✅ ALL 12 DONE (see S2.5 below). ~~3 newtype dogfood it_pending tests remain.~~ ✅ ALL 3 pass (newtype enforcement verified, compiler_types.qz BLOCKED comment updated).

S2.5: Safety Audit Holes — COMPLETE (all 12 holes fixed)

Comprehensive audit of typecheck.qz identified 15 holes in move/borrow checking. 3 fixed in S24 (NODE_FOR, NODE_IF expr, borrow-of-partial-move). 5 more fixed in S2.5 phase. Hole #10 verified with 3 tests. All 12/12 holes fixed.

FIXED (CRITICAL + MEDIUM):

#	Hole	Fix	Status
6	NODE_ASSIGN no move re-init	Added move state reset after `tc_release_old_borrow` (mirrors NODE_LET pattern)	DONE
7	NODE_STRUCT_INIT no move consumption	Added `tc_move_on_call` for IDENT field values in struct init loop	DONE
13	Lambda capture no move consumption	Added `tc_move_on_call` for each captured binding after `tc_collect_captures`	DONE
3	NODE_TRY_CATCH no move branch handling	Added snapshot/restore/merge pattern (like NODE_IF) around try body and catch handler	DONE
9	Enum payload no move consumption	Added `tc_move_on_call` for IDENT payload arguments in NODE_ENUM_ACCESS	DONE
14	Spawn no move checks for captures	Covered by #13 — spawn body is a lambda, lambda capture move tracking now active	DONE
15	Defer body no move restrictions	Already correct — defer body is type-checked in lexical order, existing NODE_CALL move tracking fires for calls in defer body	DONE
10	NODE_MATCH subject consumed but not tracked	Verified working — `tc_move_on_call` fires on match subject ident. 3 tests in s25_low_holes_spec.qz	DONE
4	NODE_WHILE move states not restored after error	Verified passing — snapshot/restore pattern works correctly. Tested in s25_low_holes_spec.qz	DONE
8	NODE_RETURN in tc_expr no move consumption	Verified passing — return move tracking fires correctly. Tested in s25_low_holes_spec.qz	DONE
12	Return borrow check single-level only	Verified passing — transitive borrow tracking works. Tested in s25_low_holes_spec.qz	DONE

FORMERLY REMAINING (now FIXED):

#	Hole	Fix	Status
5	List comprehension no move handling	Already implemented — `typecheck_walk.qz` handles NODE_LIST_COMP directly (not desugared) with snapshot/restore/merge pattern at lines 4266-4293. Confirmed with 2 tests in safety_audit_spec.qz	DONE

Phase E — Ecosystem Tooling (P0/P1)

Priority: E.2 (Package Manager) is P0 — BLOCKING | E.1 (LSP) is P1 — IMPORTANT | Remaining items are P2.

Rationale: No LSP, no package manager, no debugger, no REPL. These are table stakes for any language that wants adoption. Competitors (Zig, Rust, even V) all have these.

E.1: LSP Server

Build a Language Server Protocol implementation:

Text document sync — open, change, close
Diagnostics — publish type errors as you type (call typechecker on save)
Go to definition — symbol → file:line from scope analysis
Hover — show type of expression under cursor
Completion — suggest identifiers in scope, struct fields, enum variants
Decide: implement in Quartz (dogfooding) or Rust/TypeScript (practical)?

E.2: Package Manager (P0 Critical Path)

quartz pkg command with full dependency management:

Sub-phase	Description	Status
E.2.1	Manifest format — `quartz.toml` with name, version, description, deps, build config	TODO
E.2.2	Dependency resolution — semver-compatible resolution with conflict detection	TODO
E.2.3	Git-based fetching — clone repos, checkout tags/refs, cache locally	TODO
E.2.4	Local path dependencies — `path = "../my-lib"` for development	TODO
E.2.5	Lock file — `quartz.lock` for reproducible builds, hash verification	TODO
E.2.6	CLI commands — `quartz pkg init`, `add`, `remove`, `update`, `build`	TODO
E.2.7	Registry strategy — Git-only for v1 (like early Cargo); consider hosted registry for v2	TODO

Design decisions:

Use TOML for manifest (consistent with tooling ecosystem)
Start with git-only deps (no central registry until adoption warrants it)
Namespace packages by git org/repo (e.g., github.com/user/lib)
Lock file format: deterministic JSON or TOML

Exit Criteria: quartz pkg add github.com/user/lib && quartz pkg build resolves one dependency, compiles with it, and produces a binary. Lock file regenerates identically.

E.3: REPL

Interactive evaluation loop:

Read-eval-print for expressions (compile → lli → print result)
Accumulate definitions across lines (functions, structs visible in later expressions)
:type expr command — show inferred type
:dump command — show LLVM IR for expression
Line editing with history (use linenoise or similar via FFI)

E.4: Debugger Integration — COMPLETE ✅ (DX.1, Mar 9, 2026)

World-class lldb integration via comprehensive DWARF debug metadata:

E.5: Editor Integrations

Beyond the existing VS Code plan:

VS Code extension — TextMate grammar, format-on-save, 48 snippets — DONE (Wave 1); error squiggles deferred to E.1 LSP
Neovim — TreeSitter grammar for syntax highlighting
Emacs — quartz-mode.el with basic highlighting
JetBrains — TextMate bundle (basic highlighting)
Zed — Tree-sitter grammar (same as Neovim)

Exit Criteria: quartz-lsp provides go-to-definition, hover, and diagnostics. quartz pkg build resolves one dependency. REPL evaluates expressions.

E.6: Quake — Quartz-Native Task Runner — COMPLETE ✅

Replaced the Ruby Rakefile with a self-hosted Quartz build tool. Every rake build, rake qspec, rake format, and rake fixpoint now has a Quake equivalent that requires only the Quartz compiler and LLVM — no Ruby dependency.

Implementation: std/quake.qz (runtime library, ~460 lines) + tools/quake.qz (launcher, ~313 lines) + Quakefile.qz (19 tasks, ~620 lines). See docs/QUAKE.md for full documentation.

Sub-phase	Description	Status
E.6.1	Task definition DSL — `task()`, `task_dep()`, `task_alias()` with closures	✅ DONE
E.6.2	Dependency resolution — topological sort with diamond-dedup, cycle detection	✅ DONE
E.6.3	Shell command execution — `sh()`, `sh_capture()`, `sh_quiet()`, `sh_maybe()`	✅ DONE
E.6.4	File change detection — file-size stamp for compile cache invalidation	✅ DONE
E.6.5	Built-in tasks — 19 tasks: build, qspec, format, fixpoint, release, snapshots, etc.	✅ DONE
E.6.6	CLI interface — standalone `quake` binary with launcher + compiled Quakefile	✅ DONE
E.6.7	Quakefile format — `Quakefile.qz` (Quartz source, maximum dogfooding)	✅ DONE
E.6.8	Migration — all Rakefile tasks ported, CLAUDE.md/GEMINI.md/README updated	✅ DONE

Design decisions (resolved):

✅ Standalone binary (quake) — simpler, no compiler coupling
✅ Quartz source (Quakefile.qz) — maximum dogfooding, tasks are functions
✅ Cross-session lock was external (retired) — orthogonal concern
✅ General-purpose API — std/quake.qz usable by any Quartz project

Exit Criteria: ✅ quake build && quake qspec && quake fixpoint produces identical results to the Rake equivalents. Rakefile retained as legacy fallback but Quake is now the primary tool.

Phase B — Benchmark Integrity (P2)

Priority: P2 — DESIRABLE | Honest benchmarks build credibility; misleading ones destroy it.

Rationale: The headline “beats C” benchmark compares Quartz’s bump allocator against C’s malloc — apples to oranges. Every benchmark must compare equivalent algorithms with equivalent allocation strategies.

B.1: Fair Benchmark Suite

binary_trees: Add C version with bump allocator (same allocation strategy as Quartz)
binary_trees: Add Quartz version with malloc (same allocation strategy as C)
Ensure all implementations solve the same problem with the same algorithm
Add benchmark runner that reports mean, stddev, and confidence intervals (not single runs)
Document: which benchmarks test language overhead vs. which test allocator performance

B.2: Struct-Heavy Benchmarks

These expose the real cost of the i64-everywhere model:

nbody — N-body simulation with struct-heavy particle arrays ✅ (1.30x vs C)
json_parse — Parse a 1MB JSON file using the stdlib parser ✅ (2.48x vs C — unfair benchmark, Quartz allocates strings while C skips)
compiler_self — Time the compiler compiling a medium program (real workload)
linked_list — Insert/traverse/delete (exposes heap allocation overhead) ✅ (1.80x vs C)
hash_map_bench — HashMap operations at scale ✅ (1.21x vs C)

B.3: Comparison Methodology — COMPLETE

Publish benchmark methodology document (docs/BENCHMARKS.md) ✅ (Feb 28, 2026 — 11 benchmark pairs, fairness principles, compilation pipeline, measurement with hyperfine + fallback)
All benchmarks run with hyperfine (statistical rigor) ✅
All competitors compiled with equivalent optimization flags ✅ (Quartz: llc -O2, C: clang -O2)
Results include hardware specs, OS version, compiler versions ✅ (template in BENCHMARKS.md)
Update README benchmark table with fair, reproducible numbers

B.4: Performance Optimization — PHASES 1-5 COMPLETE (Mar 5, 2026)

Root cause analysis revealed performance gaps were not from the i64 memory model, but from 3 infrastructure bugs and 2 missing optimizations.

Phase 1: `opt -O2` Pipeline — COMPLETE

The Quartz build pipeline was missing LLVM’s entire middle-end optimization suite. llc -O2 is backend-only (instruction selection, register allocation). Adding opt -O2 before llc enables mem2reg, SROA, GVN, LICM, SCEV, and loop vectorization.

Added opt -O2 to benchmarks/run.sh compilation pipeline
Added OPT variable with auto-discovery
Verified opt -O2 works on compiler self-compilation (optimizer fixpoint gen3-opt == gen4-opt)

Phase 2: HashMap FNV-1a Hash Function — COMPLETE

All hashmap operations used linear scan from index 0 — every operation was O(n). Fixed with FNV-1a 64-bit hash and proper open-addressing with linear probing.

Added @qz_str_hash (FNV-1a 64-bit) to codegen_runtime.qz
Rewrote all 7 hashmap operations with hash-based probing (start slot = hash & (cap-1), wraparound)
Tombstone deletion (key=1 for TOMBSTONE, key=0 for EMPTY)
Fixed critical to_str heuristic bug: values > 0xFFFFFFFF were assumed to be strings, but block handles are heap pointers (not strings). Added length < 1GB + null terminator validation.
3-stage bootstrap verified, optimizer fixpoint verified

Phase 3: Vec Data Pointer Hoisting — SKIPPED

Not needed — opt -O2 LICM already handles this. Sieve 6.07x→1.00x, matrix 6.60x→1.00x demonstrate LLVM handles it.

Phase 4: Benchmark Accuracy — COMPLETE

Phase 4.1: Verified qz_str_get_len is inlined by opt -O2 (0 surviving call sites)
Phase 4.2: Fixed json_parse benchmark fairness — replaced heap-allocating parse_string/parse_number with zero-allocation skip_string/skip_number matching C algorithm
Phase 4.3: Fixed struct_heavy “hang” — was parse error from escaped angle brackets (\<Int\> → <Int>), not a compiler hang

Phase 5: LLVM Metadata — COMPLETE (inbounds + align 8; TBAA deferred)

Phase 5.1: Added getelementptr inbounds to all Vec element, struct field, and header GEPs across codegen.qz, codegen_intrinsics.qz, codegen_util.qz
Phase 5.2: Added align 8 to all i64 loads/stores across codegen.qz, codegen_intrinsics.qz, codegen_util.qz
Phase 5.3: TBAA metadata — deferred (requires threading metadata IDs through entire CodegenState; complexity/risk too high for marginal gain)

Results (best of 5 runs, Quartz vs C with `opt -O2`)

Benchmark	Before	After Phase 1+2	After Phase 3-5	vs C
fibonacci	1.26x	1.00x	1.00x	Parity
sum	108x	1.00x	1.00x	Parity (SCEV folds)
sieve	6.07x	1.00x	1.00x	Parity
matrix	6.60x	1.00x	1.00x	Parity
string_concat	1.14x	1.00x	1.00x	Parity
binary_trees	1.44x	1.33x	1.20x	Near parity
binary_trees_bump	1.09x	1.00x	1.00x	Parity
nbody	2.33x	1.30x	1.29x	Good
hash_map	1044x	1.21x	1.16x	Near parity
linked_list	2.24x	1.80x	1.42x	Good
json_parse	12.47x	2.48x	0.22x	Quartz 4.5x faster
struct_heavy	HANGS	HANGS	1.0x	Parity (with `--stack-alloc`)

9 of 12 benchmarks at C parity. json_parse: Quartz outperforms C (length-prefixed strings eliminate strlen in sb_append). linked_list improved 1.80x→1.42x from inbounds/align metadata. struct_heavy: M.R.8 --stack-alloc + opt -O2 eliminates ~15M malloc calls → C parity (0.01s vs 0.01s, 3.8MB vs 3.7MB). Without --stack-alloc: 6x (malloc path, safe at all optimization levels).

Exit Criteria: Every benchmark in the README has an equivalent implementation across all compared languages, using the same algorithms and allocation strategies. Results are reproducible by anyone.

Phase P — Production Engineering (P1)

Priority: P1 — IMPORTANT — Incremental + separate compilation are critical for any project beyond toy size.

P.1: Error Recovery — COMPLETE (Phase D)

Parser: synchronize on 14 declaration-starter tokens after error — continue parsing (up to 20 errors)
Typechecker: error limit (30), duplicate line+col suppression
Report up to 20 parser errors and 30 type errors per file
Suppress cascading errors — duplicate location dedup + TYPE_ERROR propagation

P.2: Incremental Compilation — TIER 0 + TIER 1 + TIER 2 + AST CACHE COMPLETE

Tier 0 (Pre-Resolution Quick-Check): Before any parsing, checks if ALL source files are unchanged since last build. Compares content hashes stored in .quartz-cache/module_paths.txt. If all match, returns cached .quartz-cache/whole_program.ll immediately. 9s → 23ms (400× speedup), byte-identical output.

Tier 1 (Per-Module Codegen Caching): Builds dependency graph during resolution (dep_graph.qz). Compares per-module content hashes with cached dep graph. Computes interface hashes after typecheck for early cutoff. Uses cg_codegen_incremental() for selective codegen. Pre-loads cached string pool to maintain stable @.str.N indices. Uses deterministic metadata slots: function i starts at i * 128. Saves per-module IR fragments with metadata headers.

Tier 2 (Selective TypeCheck + MIR Skip): Skips tc_function body-checking for functions from unchanged modules (unless generic, for monomorphization safety). MIR lowering uses existing _mir_should_lower infrastructure to skip function lowering for unchanged modules. Interface hash computation moved before tc_function loop (reads only from tc.registry, populated by Phase 4.0-4.1). --explain-cache output shows changed modules, recompile set, module/function skip counts. 10.4s cold → 6.9s incremental (34% reduction, 1367/1375 functions skipped when only a leaf module changes). 7 tests in incr_tier2_spec.qz.

Binary Vec Serialization + AST Cache V3: 4 new binary Vec I/O intrinsics (vec_save, vec_load, strvec_save, strvec_load) for fast binary serialization (~166 lines LLVM IR runtime). Registered in mir_intrinsics, typecheck_builtins, codegen_intrinsics. AST cache rewritten to binary format (14 files/module: header.txt + 8 vec_save + 3 strvec_save + 2 children vectors) instead of text-based escape/unescape. Resolver checks AST cache before lexing/parsing — cache hit skips lexer+parser entirely.

Files: dep_graph.qz (NEW), build_cache.qz (string pool save/load, AST cache save/load, explain-cache getter), codegen.qz (cg_codegen_incremental, cg_extract_module, fragment pre-scan), codegen_intrinsics.qz (vec_save/vec_load/strvec_save/strvec_load dispatch), codegen_runtime.qz (qz_vec_save/qz_vec_load/qz_strvec_save/qz_strvec_load runtime helpers), mir_intrinsics.qz (4 intrinsic recognitions), mir_lower.qz (_mir_should_lower selective skip), typecheck_builtins.qz (4 return type registrations), quartz.qz (Tier 0 quick-check, Tier 1-2 orchestration, generic func handles, TC skip counters, explain-cache output), resolver.qz (dep graph wiring, AST cache load/save), typecheck.qz (tc_compute_interface_hash), Quakefile.qz (QSpec --no-cache), subprocess.qz (—no-cache for all subprocess compiles)

Key bugs fixed: (1) Cross-test cache contamination — QSpec --no-cache prevents shared .quartz-cache/. (2) Same-program check — module set comparison prevents incremental mode for different programs. (3) Missing fragment pre-scan — verify cached fragments exist before codegen loop. (4) String pool empty string — count-first save format. (5) Cache directory SIGSEGV — fragment saving only in incremental path. (6) __main__ content hash set at end of compilation, not after resolution — caused false change detection. (7) AST cache cross-program contamination — subprocess compiles share .quartz-cache/ast/, fixed by --no-cache in subprocess.qz.

Known limitation: e-graph optimizer 2-cycle oscillation (gen3!=gen4, gen3==gen5) — pre-existing, not caused by P.2.

Content-hash each source file — DONE (FNV-1a 64-bit via content_hash.qz)
Dependency tracking — recheck only files that import changed files — DONE (dep_graph.qz with BFS invalidation + interface hash early cutoff)
Cache LLVM IR per module — load cached fragments for unchanged modules — DONE (.quartz-cache/modules/{name}.ll)
Selective TypeCheck — skip body-checking for unchanged modules — DONE (Tier 2, generic safety guard)
Selective MIR lowering — skip function lowering for unchanged modules — DONE (Tier 2, mir_lower_set_recompile)
Cache parsed AST per module — binary Vec serialization intrinsics — DONE (14 binary files/module, resolver cache hit skips lexer+parser)
Separate compilation — per-module .o files (P.3) ✅ DONE (Mar 2, 2026)

P.3: Separate Compilation — CORE COMPLETE

Monolithic-then-split approach: compiler runs as one invocation through lex → parse → typecheck → MIR, then splits at codegen into per-module .ll files. Each is independently compilable by llc. build:separate Quake task handles parallel llc + .o caching.

P.4: Diagnostic Quality — COMPLETE (Phase D)

Source spans — caret underlines with span length for known identifiers
Source context — show source line + caret line for each error
Fix-it suggestions — “did you mean ‘var’?” for immutability, expected/found for type mismatches, borrow help
Error codes — 24 QZ codes (QZ0101–QZ1215), --explain documentation for 14 codes (added QZ1212, QZ1214, QZ1215)
Color output — ANSI colored severity, blue gutters, red/yellow carets, bold messages
Notes/help system — = help: ... lines attached to diagnostics
JSON output — --error-format=json for IDE/LSP integration
Fuzzy matching — Damerau-Levenshtein + prefix matching for vars, funcs, structs, enums, types

P.5: Compiler Performance — COMPLETE (15.6s → 2.3s, 85% total reduction)

Design doc: docs/design/STRING_INTERNING_PLAN.md (Feb 28, 2026), docs/design/P5_PERFORMANCE_PLAN.md (plan mode, Mar 8, 2026)

Results: Three rounds of optimization achieved 85% total wall-clock reduction (15.6s → 2.3s):

Round 1 — String interning (Feb 28–Mar 5): 15.6s → 9.7s (38% reduction). Lexer + AST + TC Registry interning.
Round 2 — HashMap algorithmic fixes (Mar 8): 12.6s → 7.3s wall clock, 10.9s → 6.0s CPU (42%/45% reduction).
Round 3 — P.5.TC Typecheck HashMap optimization (Mar 8): TC 4.5s → 490ms (89% reduction, 9.1× speedup). Total ~6.4s → 2.3s (64% reduction).

Phase timing breakdown (after P.5.TC, --timing flag):

Phase	Time	%
lex	1ms	0.0%
parse	43ms	1.9%
resolve	1,127ms	48.2%
typecheck	490ms	21.0%
mir_lower	451ms	19.3%
mir_opt	0ms	0.0%
codegen	235ms	10.1%

Completed phases:

Rejected phases:

~~Phase 3.2-3.3: Codegen string concat elimination~~ — REJECTED. Codegen is only 4% of compile time (~1% wall gain). The transformation expands each 1-line concat into 4-7 multi-emit calls, making codegen files larger and harder to read. The concat form shows the full LLVM IR template at a glance; multi-emit scatters intent across many calls. Worse on every axis.
~~Phase 5.1: Arity overload HashMap~~ — REJECTED. MIR lowering is only 7.1% of compile time. Diminishing returns after Phases 1-2.

Deferred phases (genuine future candidates):

String interning — Step 4: MIR context interning (2-5% marginal gain, codegen must resolve to strings for LLVM IR)
Arena allocation for AST nodes — stop malloc’ing every node
Parallel type checking (per-module, dependency-aware)
Target: compile 50K lines in < 2 seconds

Next frontier: Resolve optimization (48% of compile time, 1.1s). MIR optimization (19%, 451ms). These two phases account for 67% of CPU time.

Known bug: Multi-argument extern "C" declarations crash in multi-module compilation context (“index out of bounds: index 1, size 1” in cg_emit_intrinsic). 0-argument extern works fine. Pre-existing bug, worked around by using clock() (0-arg) instead of gettimeofday (2-arg).

Exit Criteria: ~~The compiler reports multiple errors per file.~~ ✅ DONE (Phase D). ~~Error messages include source context and suggestions.~~ ✅ DONE (Phase D). ~~Profile self-compilation.~~ ✅ DONE (P.5, Feb 28). ~~Benchmark methodology.~~ ✅ DONE (B.3, Feb 28). ~~Incremental compilation design.~~ ✅ DONE (P.2, Feb 28). ~~Compiling unchanged files is instant.~~ ✅ DONE (P.2 Tier 0: 9s → 23ms). ~~Separate compilation works.~~ ✅ DONE (P.3, Mar 2). ~~Per-phase timing instrumentation.~~ ✅ DONE (P.5 Phase 0, Mar 8). ~~Algorithmic hotspot elimination.~~ ✅ DONE (P.5 Phases 1-6 + P.5.TC Phases 1-4, Mar 8). ~~Typecheck optimization.~~ ✅ DONE (P.5.TC, TC 4.5s → 490ms). Compiler handles 50K lines in <2s (requires resolve optimization).

Phase W — Launch Readiness (P1)

Priority: P1 — IMPORTANT — Public-facing polish. Depends on STD (stdlib usable), E.2 (packages work), S2 (safety claims are real).

W.2: Examples Gallery — 17/17 COMPLETE

All examples complete:

bare_metal.qz — IMPLEMENTED: True freestanding Quartz binary running on QEMU virt (aarch64). tools/baremetal/hello.qz writes to PL011 UART at 0x09000000 via volatile_store<U8>. Uses @naked _start with inline asm, ptr_read_byte for string iteration, linker script at tools/baremetal/aarch64-virt.ld (entry 0x40000000, 64KB stack). QSpec tests in baremetal_spec.qz. The examples/bare_metal.qz file contains the simulated version for environments without QEMU/cross-toolchain.

W.3 Remaining: Doc Tooling

Generate JSON index for potential static site integration
Consider extending tools/doc.qz to emit HTML directly

W.4: Website

Landing page: tagline, 3 code examples, key stats
Getting Started: install LLVM, clone repo, hello world
Language Reference: QUARTZ_REFERENCE.md rendered as HTML
API Reference: auto-generated from doc comments (W.3)
Examples Gallery: the examples from W.2 with syntax highlighting
Playground: “Coming soon” placeholder (or WASM if time permits)

W.5: Literate Source Site

tools/literate.qz reads .qz source files
##! module headers rendered as page introductions
## function docs as rich prose between syntax-highlighted code
Cross-linked identifiers — click a function call, jump to definition
Nav sidebar from module directory structure

W.6: VS Code Extension — PARTIAL

TextMate grammar for syntax highlighting — DONE (Wave 1: 560-line .tmLanguage.json)
Format-on-save via quartz --format — DONE (Wave 1: extension.ts)
48 code snippets — DONE (Wave 1: quartz.json)
Language configuration (folding, indentation, brackets) — DONE (Wave 1)
Compiler errors as basic diagnostics (bridge to E.1 LSP)
Publish to VS Code marketplace

W.7 Remaining: CLI

quartz init my_project — scaffold project with quartz.toml

W.8: Launch Blog Post

“I Built a Self-Hosting Language in 56 Days” — engineering story
Structure: bootstrap → fixpoint → type inference → LLM methodology → alive
Honest assessment: what works, what doesn’t, what’s next
Link to playground, examples, literate source, benchmarks

Future: Phase V — Dogfooding Vision

Prove the language by building the entire web presence in it.

Step	Description	Status	Depends On
1	Web server written in Quartz	DONE	`std/net/http_server.qz` — routing, path params, CORS, TLS
2	Web framework on Quartz server	TODO	Step 1 ✅
3	Marketing site in Quartz	TODO	Step 2, WASM target
4	Canvas-based WASM rendering	TODO	Radical: render as canvas app

Step	Description	Status
R.0	Deep research: Flux, LiquidHaskell, Thrust	TODO
R.1	Design integration with existential type model	TODO
R.2	SMT solver integration (Z3)	TODO
R.3	Core refinement type checker	TODO
R.4	Gradual adoption: runtime checks → static proofs	TODO
R.5	AI-assisted spec generation (stretch)	TODO

Future: Phase G — GPU Compute

Step	Description	Status
G.0	Enhanced SIMD hints (build on S.3-S.9)	TODO
G.1	`@gpu` + LLVM NVPTX backend	TODO
G.2	Host-side kernel launch codegen	TODO
G.3	Multi-vendor (AMD via AMDGPU)	TODO
G.4	Kernel fusion / advanced optimization	TODO

Future: Phase O — Compiler Optimization

Item	Priority	Status
LLM-driven optimization (experimental)	LOW	TODO

All other optimization items (MIR optimizer, DCE, TCO, inlining, strength reduction, e-graph) are COMPLETE. See full archive.

Future: Phase A — AI Integration

Item	Priority	Status
LLM directive design session	HIGH	TODO
`@ai("prompt")` function annotations	MEDIUM	TODO
Constrained decoding (LMQL-style)	LOW	TODO

Dependency Graph — Production 3.0 Critical Path

                     Current State (v5.25.0-alpha)
                              │
          ┌───────────────────┼───────────────────┐
          │                   │                   │
     ═══ P0: BLOCKING ═══════╪═══════════════════╪═════
          │                   │                   │
    ┌─────▼──────┐    ┌──────▼───────┐    ┌──────▼──────┐
    │ STD        │    │ U.9          │    │ S2.4        │
    │ Stdlib     │    │ Intersection │    │ Lifetime    │
    │ [NEW]      │    │ Completion   │    │ Inference   │
    └─────┬──────┘    └──────┬───────┘    └──────┬──────┘
          │                  │                   │
    ┌─────▼──────┐           │                   │
    │ E.2        │           │                   │
    │ Package    │           │                   │
    │ Manager    │           │                   │
    └─────┬──────┘           │                   │
          │                  │                   │
     ═══ P1: IMPORTANT ══════╪═══════════════════╪═════
          │                  │                   │
    ┌─────▼──────┐    ┌──────▼───────┐    ┌──────▼──────┐
    │ E.1 LSP   │    │ SPEC         │    │ P.2/P.3     │
    │ Server    │    │ Formal Spec  │    │ Incremental │
    │           │    │ [NEW]        │    │ Compilation │
    └─────┬──────┘    └──────┬───────┘    └──────┬──────┘
          │                  │                   │
          └──────────────────┼───────────────────┘
                             │
                      ┌──────▼───────┐
                      │ W.4 Website  │
                      │ + W.8 Launch │
                      └──────┬───────┘
                             │
                         ════╧════
                       v6.0.0 Release
                      Production 3.0
                         ════╤════
                             │
     ═══ P2: DESIRABLE ══════╪════════════════════════
          │                  │                   │
    ┌─────▼──────┐    ┌──────▼───────┐    ┌──────▼──────┐
    │ B          │    │ M.R Memory  │    │ X Compiler  │
    │ Benchmarks │    │ Model Rest  │    │ Architecture│
    └────────────┘    └──────────────┘    └─────────────┘
                             │
     ═══ FUTURE ═════════════╪════════════════════════
          │                  │                   │
    ┌─────▼──────┐    ┌──────▼───────┐    ┌──────▼──────┐
    │ R          │    │ G GPU       │    │ A AI        │
    │ Refinement │    │ Compute     │    │ Integration │
    └────────────┘    └──────────────┘    └─────────────┘

Critical Path: STD → E.2 → W.4 (the stdlib must exist before packages can be built; packages must work before a useful website can be launched). In parallel: U.9, S2.4, and SPEC can all proceed independently.

Parallelism: STD, U.9, and S2.4 have zero dependencies on each other (different parts of the compiler). E.1 (LSP) benefits from SPEC (formal grammar). P.2/P.3 (incremental compilation) is independent. B, M.R, and X are all independent polish items.

Design Decisions Required Before Proceeding

Decision	Phase(s)	Key Questions	Status
Memory model v2	M	Full type erasure vs. sized types vs. hybrid? Gradual migration or clean break?	COMPLETE — Hybrid (2A comptime + selective 2B monomorphization), gradual migration. Design: `docs/design/MEMORY_MODEL_V2.md`. Phases 1-3 implemented.
Borrow checker scope	S2	Rust-level lifetimes vs. Austral-simple vs. Vale-generational?	PARTIAL — S2.1-S2.3 done (Austral-style second-class refs), S2.4 lifetime inference remains
LSP implementation language	E.1	Quartz (dogfooding) vs. TypeScript (practical) vs. Rust (performant)?	NEEDS DECISION
Package registry	E.2	Git-only vs. hosted? Central registry vs. distributed?	NEEDS DECISION
Macro hygiene model	F.5	Scheme-style hygienic vs. Rust-style `macro_rules!` vs. AST transform?	NEEDS DESIGN
Separate compilation strategy	P.3	~~Whole-program monomorphization vs. per-module codegen with linking?~~	✅ RESOLVED: Monolithic pipeline, split at codegen. `linkonce_odr` for generics.

API Unification Remaining Work

See docs/design/UNIFIED_API.md for the full checklist. Key pending UFCS methods:

.clear(), .contains(), .split(), .replace(), .trim() for String
.to_vec() for iterables
Various collection convenience methods
UFCS predicate methods: .empty? works for Vec and String. .some? / .none? / .ok? / .err? work (Phase 12: tc_check_enum_access returns TYPE_OPTION/TYPE_RESULT).

QSpec Test Suite Status

Current (Mar 1, 2026): 298/319 files passing, ~3,120+ active tests, ~279s (was 2337s before runner hardening)

QSpec is Quartz’s native test suite — tests written in Quartz itself, compiled by the self-hosted compiler, and run via lli (LLVM JIT) or compiled binaries. It is the primary fast test suite for development.

Runner Hardening (Mar 1, 2026)

Suite was crashing a 64GB M1 Max MacBook Pro — compiler hangs blocked the suite for 39+ minutes. Fixed:

Per-binary timeouts: compile timeout (QSPEC_COMPILE_TIMEOUT, default 60s) + run timeout (QSPEC_TIMEOUT, default 30s) via shell-level SIGALRM watchdog
Observability: output capture to /tmp/qspec_*.out, signal detection (T=timeout, S=SIGSEGV, F=failure), failure output display, per-file timing, top-10 slowest files
Developer experience: qspec_fast task (skips SSL/httpbin/spawn tests), qspec_file task (single-file runner)
Spinloop fixes: sleep_ms(1) in all networking spec wait loops (tls_spec, https_spec, buffered_net_spec)

21 remaining failures breakdown:

Category	Count	Files
Old QSpec API (subprocess specs)	15	wasi, dce, inlining, freestanding, cross_compilation, cimport, baremetal, simd_convert, auto_vectorize, regalloc_hints, c_backend, simd_gather_scatter, optimization_flag, stack_trace, type_errors, cross_platform_stdlib
Compiler hang (compile timeout)	3	ffi_spec, networking_spec, variadic_extern_spec
Network test (run timeout)	1	https_spec (external httpbin.org)
~~Pre-existing failure~~	1	~~incr_tier2_spec~~ FIXED — Tier 2 incremental correctness (seed propagation)

Key Metrics

Metric	Value
QSpec files	292 (+qzi_roundtrip_spec)
QSpec files passing	292 (0 failures from our changes)
Active `it` tests	~3,120+
Property tests	40+
Total active	~3,120+
Pending tests (placeholders)	~24 (10 hard blockers + 14 networking concurrency)
Runtime	~200s

RSpec files	215
RSpec test cases	3,274
RSpec failures	2 (pre-existing)
RSpec runtime	~8 min

Pre-existing failures (4 — Group A actively working on fixes):

packed_arrays_spec — compile error
simd_f32x4_spec — compile error
simd_f32x8_spec — compile error
~~inline_struct_vec_spec — exit 256~~ FIXED by M.R.5 vec_get deep copy (alloca + memcpy for @value structs)
~~escape_analysis_spec — exit 256~~ FIXED by M.R.2 (heap-promotion replaces QZ1220 rejection)

Parity with RSpec

Category	Count
Files ported to QSpec (exist in both)	~180 (84% of RSpec)
RSpec-only (not portable)	36
QSpec-only (new coverage)	~34

QSpec runs ~4x faster than RSpec (~115s vs ~8 min) by compiling and running natively rather than shelling out to the compiler per test.

36 RSpec-Only Files (Permanently in RSpec)

These test categories cannot be expressed in QSpec:

Category	Files	Reason
IR inspection (RSpec-only)	`dce`, `gvn`, `licm`, `inlining`, `strength_reduction`, `regalloc_hints`, `optimization_flag`, `auto_vectorize`	Need IR output analysis from optimized pipeline
Compile-error tests (RSpec-only)	`error_messages`, `type_errors`	Need error checks only in C bootstrap
FFI / C interop	`ffi`, `ffi_memory`, `ffi_strings`, `cimport`, `c_backend`	Need C toolchain
Cross-compilation	`baremetal`, `cross_compilation`, `cross_platform_stdlib`, `freestanding`, `wasi`	Need target-specific toolchains
Networking / I/O	`event_loop`, `gossip_chat`	Need runtime services unavailable in lli. Note: networking/file_io now have QSpec coverage via compiled binaries (not lli) — tcp_spec, tls_spec, https_spec, buffered_net_spec, network_timeout_spec
SIMD-specific	`simd_convert`, `simd_fma`, `simd_gather_scatter`	Need SIMD runtime
Other	`arena_type`, `docstrings`, `hashmap_parameterized_type`, `self_hosted_ident`, `stack_trace`, `thread_local`, `variadic_extern`	Various lli/platform limitations

Note: With the subprocess testing infrastructure (std/qspec/subprocess.qz), QSpec can now run compile-error, IR inspection, panic/exit, and stderr tests for the self-hosted compiler. However, many compile-error checks and optimization-pass IR patterns only exist in the C bootstrap compiler, so those tests remain RSpec-only.

Pre-Existing Failures

All QSpec failures have been FIXED — 291/291 green. History:

Original 3 failures (variables name collision, match return in block expr, pattern matching return) fixed in earlier phases
2 failures (fixed_width_integers_spec, float_f32_spec) fixed in Phase 9 by adding missing import * from qspec/subprocess
3 compile-error failures (packed_arrays_spec, simd_f32x4_spec, simd_f32x8_spec) fixed by migrating f32_vec_* intrinsics to generic Vec<F32> API + 3 compiler bugs (F32 in elem_width, F32/F64 type compatibility, vec_get F32→F64 promotion)
2 runtime failures (inline_struct_vec_spec, escape_analysis_spec) — escape_analysis_spec 4 pending tests activated via M.R.2 heap-promotion (was QZ1220 rejection, now transparent heap-promote). inline_struct_vec_spec FIXED — vec_get/vec_get_unchecked now perform deep copy (alloca + memcpy) for @value structs, 8/8 tests passing

Pending Tests — Breakdown by Blocker (updated Mar 2, 2026)

Tests marked it_pending that remain as placeholders. Most original blockers have been resolved.

Blocker	Tests	Nature
HTTPS/TLS network tests	9	https_spec — local server tests require concurrency infrastructure (spawn/join, task_group)
PCRE2 in lli	3	regex_advanced_spec (2) + vec_string_spec (1) — permanent platform limitation
Raw arena API tracking	2	arenas_advanced_spec — only block syntax and pool API trigger safety tracking
Type model (existential)	2	type_errors_spec (1) + stack_trace_spec (1) — String passes as i64 in existential model
TLS cert validation	1	tls_spec — needs `SSL_set1_host()` + CA loading infrastructure (design limitation)
Fixed-width integers	1	fixed_width_integers_spec — htons extern FFI permanent (macro/inline in libc)
~~Partial moves (S2.P)~~	4	~~RESOLVED — QZ1216 field-level move tracking wired~~
~~Subprocess-related (11)~~	11	~~RESOLVED — ffi_spec (5), networking_spec (4), variadic_extern_spec (2) activated~~
~~Vec<@value> deep copy~~	1	~~RESOLVED — vec_get/vec_get_unchecked memcpy for @value structs~~
~~QZI serialization~~	14	~~RESOLVED — new self-hosted/shared/qzi.qz module, 14 tests passing~~
~~Arena subprocess~~	5	~~RESOLVED — escape, allocator trait, typed allocator, arena pools, pool destroy~~
Remaining	18	9 permanent/platform + 9 HTTPS network concurrency

Previously blocked, now FIXED: Safe navigation (Phase 19), record types (Phases 19+22), mutable borrows (Phase BC), modules/imports (Phases 19-21), slices (Phase 22), Fn in struct field (Phase F-Delta), packed structs (Phase 22), conditional compilation (Phase 22), name resolution (Phase 21), user macros (Phase 18), arenas (Arena Safety Analysis), regex match arms (Phase 22), cancel_token builtins (Phase U 8F).

Subprocess infrastructure (COMPLETE): std/qspec/subprocess.qz provides assert_compile_error, assert_compile_error_with_fixtures, assert_compile_fails, assert_ir_contains, assert_ir_not_contains, assert_run_exits, assert_run_panics, assert_run_stderr_contains, assert_run_stdout_eq, plus _with_flags variants (subprocess_compile_with_flags, subprocess_run_with_flags, assert_ir_contains_with_flags, assert_run_panics_with_flags, assert_run_exits_with_flags) for passing extra compiler flags like --overflow-check and --no-opt. Uses system() + temp files + env vars (QUARTZ_COMPILER, QUARTZ_STD, QUARTZ_LLI, QUARTZ_FIXTURES). Fixture-aware variants compile test programs with -I fixtures/ for cross-module error testing.

Self-Hosted Parser Limitations Affecting QSpec

Known limitations (~~strikethrough~~ = FIXED):

Limitation	Status
~~`&` parsed as borrow, not bitwise AND~~	RESOLVED — `&` is context-sensitive: prefix = borrow (`&x`, `&mut x`), infix = bitwise AND (`a & b`). Both work correctly. `band()` still available as alternative
~~`\|` ambiguous with closure syntax~~	RESOLVED — pipe lambda syntax (`\|x\| expr`) was removed (LEO). `\|` now cleanly serves bitwise OR, union types, and or-patterns. `bor()` still available as alternative
~~`<<` / `>>` parsing issues~~	FIXED (Phase 12) — trailing `<<`/`>>` continues across lines
~~`{ }` block expressions~~	FIXED (Phase 12) — keyword-prefixed `{ if/var/while/for/match/return ... }` works
~~`m["key"]` bracket syntax~~	FIXED — works directly
~~`??` nil coalescing~~	FIXED — OP codes renumbered
~~Match guards `n if expr =>`~~	FIXED — all pattern types
~~`do...end` in match arms~~	FIXED — works in all arms
~~Unqualified enum patterns~~	FIXED — `Variant(x)` works
~~Pipeline `\|>` operator~~	FIXED — parser + codegen
~~`#{}` in closures~~	~~Causes infinite loop/OOM~~ — CONFIRMED WORKING since Sprint 4 (8 parser tests, 537 uses in compiler). The “named helper” advice was for closure-count SIGSEGV from recursive capture walker (fixed Mar 2026 with iterative worklist).
~~`{key: val}` shorthand hashmap~~	FIXED (Phase 12) — emits string keys; `hashmap_get(m, "key")` works
~~Binary literals `0b1010`~~	FIXED — 0b/0B prefix + numeric underscores
~~Literal suffixes `42_u8`~~	FIXED — lexer suffix recognition + parser propagation to AST str2
~~Curly lambda `{ x -> expr }`~~	FIXED (Phase 10) — standalone + trailing; multi-param `{ x, y -> }` only in trailing position
~~`do..end` standalone blocks~~	FIXED (Phase 10) — nullary → NODE_BLOCK, parameterized → NODE_LAMBDA

Commands Reference

# Full test suite
rake test

# Build self-hosted compiler
rake build

# Fixpoint validation (ALWAYS RUN AFTER COMPILER CHANGES)
rake quartz:validate

# Rebuild C bootstrap
make -C ../quartz-bootstrap

# Debug compiler output
./self-hosted/bin/quartz --dump-ast file.qz
./self-hosted/bin/quartz --dump-mir file.qz
./self-hosted/bin/quartz --dump-ir file.qz

Quartz Language Roadmap

Principles

Priority Stack — Language Hardening First

P0: Language Completeness & Correctness

P1: Stress Test & Adversarial Hardening

P2: Compiler Engineering

P2.5: Execution Plan — Stack-Ranked with Parallel Tracks

Tier 0: Safety Foundation (fix the floor before building higher)

Tier 1: Test Hardening (you can’t prove correctness without adversarial tests)

Tier 2: Language Features — Quick Wins (simplest first, each informs the next)

Tier 3: Correctness — Hardening the Core

Tier 4: Language Features — Medium Complexity

Tier 5: Language Features — Hard (architectural changes)

Tier 6: Type System Completion

Tier 7: Targets & Backends

Tier 8: Developer Experience

Final: Specification as Mathematical Proof

Parallel Execution Map

P3: Platform & Ecosystem (DEFERRED)

LEO: Language Ergonomics Overhaul (Mar 3, 2026) ✅ COMPLETE

LFA: Language Freeze Audit (Mar 4, 2026) — ALL PHASES COMPLETE (except C.6, G deferred)

Future: Research & Moonshots

STRESS-PENDING: Pre-Existing Limitations to Fix

Macro Subsystem (10 pending → 0 pending) ✅ RESOLVED

Collections (3 pending → 0 pending) ✅ RESOLVED

Safety Combined (3 pending → 0 pending) ✅ RESOLVED

Remaining: 0 pending ✅ ALL RESOLVED

Completed Phases

Integration Test Failures

Phase F: Feature Gaps & Type System Polish (Feb 24, 2026)

Phase TH: Type Hygiene — Proper Type Annotations for Self-Hosted Compiler

Tier Status

Tier 5: Mass Newtype Dogfooding (Feb 24, 2026)

Tier 1: Struct Field Annotations

Tier 2: Function Parameter & Return Type Annotations

Tier 3: Eliminate as_int()/as_string() Pattern

Tier 4: Local Variable Annotations

Tier 5: Newtypes for Semantic Distinction

Outcomes

Completed Sprint Detail (Summary)

Integration Test Status

Sprint 1: Extend Blocks, Operator Overloading & @field Sigil — COMPLETE

Sprint 2: Map Comprehensions — COMPLETE

Sprint 3: Visibility, Variadic Extern, Const Eval — COMPLETE

Sprint 4: Parser Workaround Elimination — COMPLETE

Sprint 5: API Unification Completion — COMPLETE

Sprint 6: Remaining RSpec Failures — COMPLETE

Sprint 7: QSpec Activation & Property Testing Adoption — COMPLETE

Sprint 8: Documentation & Polish — COMPLETE

Sprint Summary

QSpec Activation Plan (Post-Sprint)

Phase 1 Quick Wins — COMPLETE

Phase 2: Monomorphization Engine — COMPLETE

Phase 3: Drop Codegen + Test Harvesting — COMPLETE

Phase 4: Compile-Error Sweep + TOML Token Helpers — COMPLETE

Phase 5: Multi-Module Validation + Drop Scope Fixes + Compile-Error Detection — COMPLETE

Phase 6: Concurrency + Generic Functions + Targeted Fixes — COMPLETE

Phase 7: F32 Fix, Literal Suffixes, Drop/Multi-Module Harvest — COMPLETE

Structural Method Dispatch — COMPLETE

Phase 8: Record/Structural/AssocFn Probes — COMPLETE

Phase 9: Fix Pre-Existing QSpec Failures + Trait Default Inheritance — COMPLETE

Phase 10: Parser Block Expressions + Strategic Harvest — COMPLETE

Phase 11: Task Group + Generics + Constant Dedup — COMPLETE

Phase 12: Generics Completion + Parser Fixes — COMPLETE

Phase 13: Parallel Test Activation — COMPLETE

Phase 14: Parallel Streams A+B — COMPLETE

Phase 15: Parallel Streams A+B — COMPLETE

Phase 17: Regex Root Cause Fix (Feb 22, 2026)

Phase 18: User Macro System — COMPLETE

Arena Safety Analysis — COMPLETE

Phase 19: Feature Completion Tier 1 — COMPLETE

Phase 20: Deep Fixes — Traits, Generic Ptypes, Record Returns — COMPLETE

Phase 21: Cross-Module UFCS Fix — COMPLETE

Phase 22: Finish Line + Phase U 8F — COMPLETE

Phase CMF: Cross-Module Fixes — COMPLETE

Phase E2B: E.2 Blocker Fixes — COMPLETE

Phase 11 Regression Fix — COMPLETE

Parallel Track A: Closure Spawn + CAS Ring Buffer — COMPLETE

Parallel Track B: SSA Naming + Private Visibility — COMPLETE

Parallel Track C: Rust-Style Diagnostic Engine — COMPLETE

Tier 3: Eliminate `as_int()/as_string()` Pattern

U.9.18 — Vtable Dispatch for Trait Intersections — PERMANENTLY DEFERRED (Future `dyn Trait` Phase)

F.8: Cross-Module String `+` Operator — FIXED