Quartz v5.25

Overnight Autonomous Work Plan — April 7, 2026

Context

This session completed:

  • DG.2 triple-quoted string dogfooding (13 files, 186 conversions)
  • API cleanup Phase 1 (band duplicate, addressof, hashmap_del rename)
  • Match arm enhancements (char patterns, negative ints, string constants)
  • Length-based pre-dispatch optimization for string match
  • 700+ arm string match dogfooding (then replaced with world-class Set lookup)
  • Unified intrinsic registry (696 intrinsics, single source of truth)
  • Bootstrap recovery from near-catastrophic binary loss
  • New golden backup protocol in CLAUDE.md

What To Work On (Stack-Ranked by Impact)

1. API Surface Cleanup — Phases 2-4 (Estimated: 2-3 hours)

Complete the remaining phases from the API cleanup plan. Phase 1 is done.

Phase 2: Remove Aliases (specs need updating)

  • Remove set_contains/Set$contains (keep set_has/Set$has) — O(1) = has per API guidelines
  • Remove set_remove/Set$remove (keep set_delete/Set$delete) — key/value deletion = delete
  • Remove standalone reverse() (keep reversed() and vec_reverse())
  • Remove standalone sort() (keep sorted() and vec_sort())
  • For each: update typecheck_builtins.qz, mir_intrinsics registry, codegen handlers, then migrate affected spec files

Phase 3: Source Migration + len Removal

  • Migrate vec_len → vec_size in compiler source (64 sites, 55 in lsp.qz)
  • Migrate sb_len → sb_size (~3 sites)
  • Remove str_len/String$len, vec_len/Vec$len, arr_len, array_len, slice_len, range_len, channel_len + UFCS variants from typecheck_builtins.qz

Phase 4: Documentation

  • Fix STYLE.md v.clear! → v.clear()
  • Update INTRINSICS.md: replace str_len refs with str_size, mark set_has as canonical
  • Update QUARTZ_REFERENCE.md: v.len() → v.size

Critical constraint: Every change requires quake build + quake fixpoint. Use the GOLDEN BACKUP PROTOCOL:

  1. NEVER overwrite quartz-golden until fixpoint passes
  2. Restore from golden on ANY failure
  3. Commit binary to git after major successful builds

2. Verify All examples/ Compile (Estimated: 1-2 hours)

Run every file in examples/ and benchmarks/ against the current compiler. Fix any breakage. This is item #1 on the ship-blocking list.

for f in examples/*.qz benchmarks/*/*.qz; do
  echo "=== $f ==="
  ./self-hosted/bin/quartz "$f" > /dev/null 2>&1 && echo "OK" || echo "FAIL"
done

Fix any failures — they might need updated syntax, new intrinsic names, etc.

3. MIR Heap Corruption Investigation (Estimated: 2-3 hours)

Root cause the bug discovered today:

  • mir_ctx_mark_struct_var → realloc → heap corruption
  • Triggered when init_intrinsic_registry() (696 map_set calls) runs during MIR lowering
  • Workaround: init before MIR lowering starts
  • Files: self-hosted/backend/mir.qz (line ~2117), the Vec that mir_ctx_get_struct_types returns

Investigation steps:

  1. Read mir_ctx_mark_struct_var and mir_ctx_get_struct_types
  2. Understand the struct_types Vec lifecycle — when allocated, when freed, who holds pointers
  3. Check if any MIR lowering code caches a pointer to struct_types that goes stale after realloc
  4. Write a targeted test that reproduces the bug (function with 100+ calls to functions that allocate)
  5. Fix the root cause (likely: cache invalidation after Vec realloc)

4. Getting Started Guide (Estimated: 1-2 hours)

Create docs/GETTING_STARTED.md — ship-blocking item.

  • Install: clone repo, ensure LLVM is installed, build
  • Hello World: write, compile, run
  • First real program: a small CLI tool using argparse + file I/O
  • Next steps: links to QUARTZ_REFERENCE.md, examples/, STYLE.md

Execution Order

  1. API cleanup Phases 2-4 (highest impact, mechanical, safe)
  2. Verify examples/ (quick validation, finds lurking bugs)
  3. MIR investigation (deep work, fixes a real bug)
  4. Getting Started guide (documentation, no compiler risk)

Golden Backup Protocol (CRITICAL)

Before EVERY quake build after compiler changes:

# Step 1: Verify golden exists
ls self-hosted/bin/backups/quartz-golden

# Step 2: Build
./self-hosted/bin/quake build

# Step 3: Verify fixpoint
./self-hosted/bin/quake fixpoint

# Step 4: ONLY after fixpoint passes, rotate golden
mv self-hosted/bin/backups/quartz-golden self-hosted/bin/backups/quartz-prev
cp self-hosted/bin/quartz self-hosted/bin/backups/quartz-golden

# Step 5: Commit binary periodically
git add self-hosted/bin/quartz && git commit -m "Update compiler binary"

IF fixpoint fails: cp self-hosted/bin/backups/quartz-golden self-hosted/bin/quartz

Key Files Reference

  • self-hosted/backend/intrinsic_registry.qz — Single source of truth for intrinsics
  • self-hosted/middle/typecheck_builtins.qz — Builtin type registrations (API cleanup target)
  • self-hosted/backend/mir.qz — MIR context (heap corruption bug location)
  • self-hosted/backend/mir_intrinsics.qz — 13 lines, imports intrinsic_registry
  • self-hosted/backend/codegen_intrinsics.qz — 152 lines, dispatch only
  • docs/Roadmap/ROADMAP.md — Roadmap (update after completing work)
  • docs/API_GUIDELINES.md — API naming conventions (has vs contains, delete vs remove)

What NOT To Do

  • Do NOT attempt the intrinsic registry refactor again (it’s done)
  • Do NOT modify mir_lower_expr_handlers.qz or mir_lower_stmt_handlers.qz without careful fixpoint testing
  • Do NOT create new modules without verifying imports resolve correctly
  • Do NOT overwrite quartz-golden until fixpoint is verified
  • Do NOT commit without running the pre-commit fixpoint hook