chore(tasks): Phase 16 codegen + Phase 17 bootstrap — 7 tasks, 158 items, ERA 1 COMPLETE

Phase 16 (ERA 1, Phase 4) — MIR→LLVM IR codegen (~76K LOC C++ → ~49K TML):
- phase16a: Types & declarations — struct layouts, function sigs (25 items)
- phase16b: Instructions — arithmetic, memory, control flow (25 items)
- phase16c: Calls & ABI — method dispatch, sret, Win64/SysV (25 items)
- phase16d: Legacy LLVM codegen — builtins, drop glue, remaining (25 items)

Phase 17 (ERA 1, Phase 5) — Bootstrap & self-hosting:
- phase17a: Query system — demand-driven pipeline (18 items)
- phase17b: CLI & tooling — dispatcher, diagnostics, test runner, formatter (24 items)
- phase17c: Bootstrap verification — Stage 0→1→2, IR-diff, TML COMPILES ITSELF (16 items)

All 7 tasks include proposals (49-98 lines each).
ERA 1 is now FULLY PLANNED: 25 tasks, 544 checklist items.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Andre Ferreira

.rulebook/tasks/TASKS-INDEX.md

@@ -1,7 +1,7 @@
 # TML Project — Task Index
 
 **Last updated**: 2026-04-05
-**Active tasks**: 39 | **Archived**: 5+
+**Active tasks**: 46 | **Archived**: 5+
 
 ---
 
@@ -171,6 +171,31 @@ Port HIR, THIR, MIR builder, and 52 MIR optimization passes from C++ to TML.
 
 **Order**: 15a → 15b → 15c → 15d (sequential)
 
+## Phase 16 — Codegen in TML (ERA 1, Phase 4)
+
+Port MIR→LLVM IR text generation (~76K LOC C++) to TML. Largest subsystem — output is text, easy to verify.
+
+| ID | Task | Status | Priority | Progress |
+|----|------|--------|----------|----------|
+| 16a | [Types & Declarations](phase16a_codegen-types-decls/) | Planned | P0 | 0/25 |
+| 16b | [Instructions](phase16b_codegen-instructions/) | Planned | P0 | 0/25 |
+| 16c | [Calls & ABI](phase16c_codegen-calls-abi/) | Planned | P0 | 0/25 |
+| 16d | [Legacy LLVM Codegen](phase16d_codegen-legacy-llvm/) | Planned | P0 | 0/25 |
+
+**Order**: 16a → 16b → 16c → 16d (sequential, 16a/16b can partially overlap)
+
+## Phase 17 — Bootstrap (ERA 1, Phase 5) 🎯 SELF-HOSTING
+
+Wire everything together, port tooling, execute three-stage bootstrap verification. **ERA 1 COMPLETE when phase17c passes.**
+
+| ID | Task | Status | Priority | Progress |
+|----|------|--------|----------|----------|
+| 17a | [Query System](phase17a_query-system/) | Planned | P0 | 0/18 |
+| 17b | [CLI & Tooling](phase17b_cli-tooling/) | Planned | P0 | 0/24 |
+| 17c | [Bootstrap Verification](phase17c_bootstrap-verification/) | Planned | P0 | 0/16 |
+
+**Order**: 17a → 17b → 17c (sequential). 17c = **TML COMPILES ITSELF**
+
 ## Research
 
 | ID | Task | Status | Priority | Progress |

.rulebook/tasks/phase16a_codegen-types-decls/.metadata.json

@@ -0,0 +1,5 @@
+{
+  "status": "pending",
+  "createdAt": "2026-04-06T01:25:21.403Z",
+  "updatedAt": "2026-04-06T01:25:21.403Z"
+}

.rulebook/tasks/phase16a_codegen-types-decls/proposal.md

@@ -0,0 +1,75 @@
+# Proposal: Codegen Types & Declarations — Rewrite in TML
+
+## Why
+
+The MIR codegen subsystem is the final C++ layer standing between an optimized MirModule and the
+LLVM IR text that LLVM compiles to native code. Its entry point (`mir_codegen.cpp`, 1,622 LOC) and
+type emission layer (`mir_types.cpp`, `llvm_types.cpp`, 1,207 LOC) are the foundation on which all
+instruction and call emission depends. Types that are laid out incorrectly corrupt every instruction
+that reads or writes a value of that type. Porting the type and declaration layer first establishes
+a verified foundation before tackling instructions and calls in phases 16b and 16c.
+
+## What Changes
+
+The C++ type emission code in `compiler/src/codegen/mir_codegen.cpp`, `mir/mir_types.cpp`, and
+`llvm/core/llvm_types.cpp` is replaced by a TML implementation in `compiler-tml/src/codegen/`.
+Function signature emission from `llvm/decl/func.cpp` (1,351 LOC) and impl/vtable emission from
+`llvm/decl/impl.cpp` (1,336 LOC) are also ported here, since they depend only on the type layer.
+
+### Architecture
+
+```
+compiler-tml/src/codegen/
+  mod.tml          — re-exports Codegen, CodegenConfig, emit_module()
+  config.tml       — CodegenConfig: target triple, data layout, opt level
+  types.tml        — LlvmType enum: I1..I64, F32/F64, Ptr, Struct, Array, Func, Void
+  layout.tml       — LayoutComputer: size/alignment/field-offsets per MirType
+  emit_type.tml    — emit_type(MirType) -> Text: MIR type → LLVM IR type string
+  emit_func.tml    — emit_func_decl(MirFunc) -> Text: define/declare line + sret/byval
+  emit_module.tml  — emit_module(MirModule) -> Text: complete LLVM IR file
+```
+
+### Key Design Decisions
+
+- **Text output via template literals** — all IR emission uses TML template literals
+  (`` `define fastcc i64 @{name}({params}) {` ``) rather than string concatenation. This matches
+  how the C++ code builds IR and keeps emission code readable and diffable.
+- **Type layout must be byte-for-byte identical to C++** — the `LayoutComputer` in `layout.tml`
+  replicates the exact field-padding rules from `llvm_types.cpp`. Any divergence corrupts sret
+  slot sizes, GEP indices, and struct constructor IR. Tests assert field offsets directly.
+- **Opaque pointer model** — the TML codegen targets LLVM 15+ opaque pointers. All pointer types
+  emit as `"ptr"` regardless of pointee type. This simplifies the type layer significantly
+  compared to the typed-pointer LLVM IR the legacy codegen sometimes emits.
+- **Named struct deduplication** — each struct name is emitted as a `%struct.Name = type { ... }`
+  definition exactly once at the top of the module. A `HashMap[Str, Bool]` tracks already-emitted
+  structs to prevent duplicate definitions, which are LLVM IR errors.
+- **sret for large return types** — structs larger than 16 bytes use the sret convention: the
+  caller allocates a stack slot and passes its address as the first argument annotated
+  `ptr sret(%struct.T) align 8`. The callee writes the result there and returns void. The
+  `emit_func_decl` function computes this from the layout, matching `func.cpp` exactly.
+- **Runtime declarations on demand** — instead of emitting all 500+ runtime function declarations
+  unconditionally (as the C++ legacy codegen does), the TML emitter tracks which extern functions
+  the module actually calls and emits only those `declare` lines. This reduces IR file size and
+  speeds up LLVM parsing.
+
+## Impact
+
+- Affected code: `compiler/src/codegen/mir_codegen.cpp`, `mir/mir_types.cpp`,
+  `llvm/core/llvm_types.cpp`, `llvm/decl/func.cpp`, `llvm/decl/impl.cpp` (all replaced)
+- Affected phases: 16b (instructions call `emit_type`), 16c (calls use sret/byval decisions)
+- Breaking change: NO — IR-diff testing ensures identical type strings and function signatures
+- User benefit: self-hosting progress; type layout logic is inspectable and modifiable in TML
+
+## Success Criteria
+
+The TML type emitter produces LLVM IR struct definitions and function declaration lines that are
+character-identical to C++ codegen output for all stdlib modules. The `LayoutComputer` produces
+field offsets that match C++ for all 40+ named struct types in the stdlib. IR-diff on 5 stdlib
+modules shows zero differences in the declarations section.
+
+## Dependencies
+
+- **Requires**: phase15d (MirModule with MirType, MirFunc available in TML)
+- **Blocks**: phase16b (instructions need `emit_type`), phase16c (calls need sret decisions)
+- **Risk**: Medium — type layout errors are silent but fatal; mitigated by per-struct layout
+  unit tests that assert field offsets before any full-module IR-diff testing begins.

.rulebook/tasks/phase16a_codegen-types-decls/tasks.md

@@ -0,0 +1,53 @@
+# Tasks: Codegen Types & Declarations — Rewrite in TML
+
+**Status**: Planned (0/25)
+**Depends on**: phase15d (optimized MirModule available in TML)
+**Blocks**: phase16b (instructions need type emission), phase16c (calls need ABI/type layer)
+**Duration**: 4–6 weeks
+**Risk**: Medium — type layouts must match C++ exactly; layout errors corrupt all downstream IR
+**C++ reference**: ~8K LOC → ~5.2K TML
+
+---
+
+## Phase 1: Module & File Structure (3 items)
+
+- [ ] 1.1 Create `compiler-tml/src/codegen/mod.tml` — module root, re-exports `Codegen`, `CodegenConfig`, `emit_module()`
+- [ ] 1.2 Create `compiler-tml/src/codegen/types.tml` — `LlvmType` enum: `I1`, `I8`, `I16`, `I32`, `I64`, `F32`, `F64`, `Ptr`, `Struct(List[LlvmType])`, `Array(LlvmType, I64)`, `Func(List[LlvmType], LlvmType)`, `Void`
+- [ ] 1.3 Create `compiler-tml/src/codegen/config.tml` — `CodegenConfig` struct: target triple, data layout string, optimize level, release flag
+
+## Phase 2: Type Emission (6 items)
+
+- [ ] 2.1 Create `compiler-tml/src/codegen/emit_type.tml` — `emit_type(t: MirType) -> Text` converting MIR types to LLVM IR type strings
+- [ ] 2.2 Implement primitive types: `I64` → `"i64"`, `I32` → `"i32"`, `Bool` → `"i1"`, `F64` → `"double"`, `Unit` → `"{}"`, `Str` → `"ptr"`
+- [ ] 2.3 Implement aggregate types: struct → `"%struct.Name"` named reference, tuple → `"{ i64, i64, ... }"` inline, array → `"[N x T]"`
+- [ ] 2.4 Implement pointer and reference types: `Ref[T]` → `"ptr"`, `MutRef[T]` → `"ptr"`, raw pointer → `"ptr"` (opaque pointer model, LLVM 15+)
+- [ ] 2.5 Implement function pointer types: `func(A, B) -> C` → `"ptr"` in opaque model; emit full signature only in function declarations
+- [ ] 2.6 Implement Maybe/Outcome layout: `Maybe[T]` → `{ i32, T_padded }` matching C++ `maybe_layout()` byte-for-byte; `Outcome[T,E]` → `{ i32, union(T,E) }`
+
+## Phase 3: Struct Layout Computation (4 items)
+
+- [ ] 3.1 Create `compiler-tml/src/codegen/layout.tml` — `LayoutComputer` struct computing size/alignment for each `MirType`
+- [ ] 3.2 Implement primitive sizes: I8=1, I16=2, I32=4, I64=8, F32=4, F64=8, Bool=1, pointer=8 (x86_64)
+- [ ] 3.3 Implement struct layout: iterate fields, insert padding bytes to meet field alignment, record field offsets; total size rounded up to struct alignment
+- [ ] 3.4 Emit named struct type definitions: `%struct.Foo = type { i64, i32, [4 x i8] }` — emit each struct exactly once, deduplicate by name
+
+## Phase 4: Function Signature Emission (5 items)
+
+- [ ] 4.1 Create `compiler-tml/src/codegen/emit_func.tml` — `emit_func_decl(f: MirFunc, cfg: CodegenConfig) -> Text` producing the `define`/`declare` line
+- [ ] 4.2 Implement calling convention annotation: `cc` field on MirFunc → `fastcc`, `ccc`, `win64cc` strings prepended to `define`
+- [ ] 4.3 Implement sret parameter: if return type is large struct, prepend `ptr sret(%struct.Name) align 8 %sret_slot` as first parameter
+- [ ] 4.4 Implement byval parameter: struct args ≤ 16 bytes passed by value → `byval(%struct.Name) align 8` annotation
+- [ ] 4.5 Implement function attributes: `nounwind`, `uwtable`, `alwaysinline`, `noinline` emitted from MirFunc attribute set
+
+## Phase 5: Module-Level Declarations (4 items)
+
+- [ ] 5.1 Create `compiler-tml/src/codegen/emit_module.tml` — `emit_module(m: MirModule, cfg: CodegenConfig) -> Text` producing complete LLVM IR text
+- [ ] 5.2 Emit module header: `; ModuleID = 'file.tml'\nsource_filename = "..."\ntarget datalayout = "..."\ntarget triple = "..."\n`
+- [ ] 5.3 Emit runtime declarations: `declare` lines for every `@extern("c")` function used in the module — only emit what the module actually uses (not all 500+ runtime functions)
+- [ ] 5.4 Emit global constants and string literals: `@str.0 = private unnamed_addr constant [N x i8] c"...\00"` for each unique string in the module
+
+## Phase 6: Differential Testing (3 items)
+
+- [ ] 6.1 Create `compiler-tml/tests/codegen/types.test.tml` — unit tests: for each MirType variant, `emit_type(t)` must equal expected LLVM IR string
+- [ ] 6.2 Create `compiler-tml/tests/codegen/layout.test.tml` — struct layout tests: compute layout of 10 stdlib structs, assert field offsets match C++ `llvm_types.cpp` output
+- [ ] 6.3 IR-diff: compile 5 stdlib modules through TML type/decl emitter → compare struct definitions and function declarations against C++ codegen output line-by-line

.rulebook/tasks/phase16b_codegen-instructions/.metadata.json

@@ -0,0 +1,5 @@
+{
+  "status": "pending",
+  "createdAt": "2026-04-06T01:25:21.854Z",
+  "updatedAt": "2026-04-06T01:25:21.854Z"
+}

.rulebook/tasks/phase16b_codegen-instructions/proposal.md

@@ -0,0 +1,91 @@
+# Proposal: Codegen Instructions — Rewrite in TML
+
+## Why
+
+The instruction emission layer translates each MIR instruction into one or more LLVM IR text lines.
+It is the highest-volume code in the codegen subsystem — arithmetic, memory, control flow, and
+aggregate operations together account for the majority of all IR output. The C++ implementation is
+spread across `compiler/src/codegen/mir/instructions.cpp`, `instructions_misc.cpp`, and five files
+in `llvm/expr/` and `llvm/control/` totaling approximately 12K LOC. Porting this layer to TML
+completes the bulk of the MIR codegen path and enables IR-diff testing on realistic programs. It
+builds directly on the type emission layer from phase16a.
+
+## What Changes
+
+The C++ instruction emission files are replaced by a TML implementation in
+`compiler-tml/src/codegen/emit_inst.tml`. The complete MirInst enum (40+ variants) is handled by
+a single dispatch function that returns a `Text` fragment for each instruction. Basic block
+iteration and function body assembly remain in `emit_func.tml` (phase16a).
+
+### Architecture
+
+```
+compiler-tml/src/codegen/
+  emit_inst.tml    — InstructionEmitter: emit(MirInst) -> Text
+                     arithmetic, comparison, bitwise (Phase 2)
+                     alloca, load, store, GEP (Phase 3)
+                     br, cond_br, switch, ret (Phase 4)
+                     extractvalue, insertvalue, phi, select (Phase 5)
+                     zext, sext, trunc, ptrtoint, inttoptr, bitcast,
+                     fpext, fptrunc, fptosi, sitofp (Phase 6)
+```
+
+### Key Design Decisions
+
+- **One Text per instruction** — `emit(inst: MirInst) -> Text` returns the full IR line including
+  leading spaces and trailing newline. The caller joins all instruction texts with no separator.
+  Template literals make each case readable: `` `  %{reg} = add nsw {ty} %{a}, %{b}\n` ``.
+- **nsw on integer arithmetic** — all signed integer arithmetic emits `nsw` (no signed wrap)
+  flags, matching the C++ default. This enables LLVM to apply algebraic optimizations. The
+  `nsw` flag is omitted only for explicitly wrapping operations (future intrinsics).
+- **Ordered float predicates** — all FCmp uses ordered predicates (`oeq`, `olt`, etc.) matching
+  the C++ codegen. Unordered predicates are not emitted unless the MIR instruction carries an
+  explicit `unordered` flag, which no current TML code generates.
+- **GEP inbounds** — all GEP instructions emit `inbounds` matching the C++ output. This is safe
+  because TML's borrow checker guarantees no out-of-bounds access at the TML level. The inbounds
+  annotation enables LLVM's alias analysis.
+- **instruction-by-instruction IR-diff** — the differential testing strategy compares individual
+  instruction outputs rather than whole-function IR. This lets early failures pinpoint exactly
+  which MIR instruction variant is emitting wrong text, without requiring full-program compilation.
+
+### Instruction → LLVM IR Mapping (summary)
+
+| MIR Instruction | LLVM IR |
+|---|---|
+| `Add(nsw, a, b)` | `%r = add nsw i64 %a, %b` |
+| `ICmp(Eq, a, b)` | `%r = icmp eq i64 %a, %b` |
+| `Alloca(T)` | `%r = alloca T, align A` |
+| `Load(T, addr)` | `%r = load T, ptr %addr, align A` |
+| `Store(val, addr)` | `store T %val, ptr %addr, align A` |
+| `GEP(base, T, [0, N])` | `%r = getelementptr inbounds T, ptr %base, i32 0, i32 N` |
+| `Br(bb)` | `br label %bb` |
+| `CondBr(c, t, f)` | `br i1 %c, label %t, label %f` |
+| `Switch(v, d, cases)` | `switch i64 %v, label %d [ ... ]` |
+| `Ret(v)` | `ret i64 %v` |
+| `ExtractValue(agg, N)` | `%r = extractvalue { ... } %agg, N` |
+| `InsertValue(agg, v, N)` | `%r = insertvalue { ... } %agg, T %v, N` |
+| `Phi([(v1,bb1),...])` | `%r = phi T [ %v1, %bb1 ], ...` |
+| `Select(c, t, f)` | `%r = select i1 %c, T %t, T %f` |
+| `ZExt(v, T)` | `%r = zext i32 %v to T` |
+
+## Impact
+
+- Affected code: `compiler/src/codegen/mir/instructions.cpp`, `instructions_misc.cpp`,
+  `llvm/expr/binary.cpp`, `llvm/expr/binary_ops.cpp`, `llvm/control/when.cpp`,
+  `llvm/expr/struct_field.cpp`, `llvm/expr/llvm_struct_expr.cpp` (all replaced)
+- Affected phases: 16c (calls extend this layer with call/invoke instructions)
+- Breaking change: NO — IR-diff testing ensures instruction-identical output
+- User benefit: self-hosting progress; every IR instruction inspectable in TML
+
+## Success Criteria
+
+`emit(inst)` produces LLVM IR text that is character-identical to C++ output for all 40+ MIR
+instruction variants. IR-diff on 10 stdlib functions shows zero instruction differences.
+
+## Dependencies
+
+- **Requires**: phase16a (emit_type, LayoutComputer, register naming infrastructure)
+- **Blocks**: phase16c (call emission extends InstructionEmitter)
+- **Risk**: Medium — large number of instruction variants, but each is mechanically straightforward.
+  The main risk is alignment values diverging from C++ layout rules; mitigated by phase16a layout
+  tests that verify field offsets before instruction emission begins.