chore(tasks): Phase 15 IR pipeline tasks — 4 tasks, 89 items

ERA 1, Phase 3: Port HIR + THIR + MIR from C++ (~40K LOC) to TML (~26K LOC):
- phase15a: HIR lowering — desugaring, monomorphization, closure capture (24 items)
- phase15b: THIR lowering — coercion insertion, exhaustiveness checking (16 items)
- phase15c: MIR builder — SSA construction, basic blocks, 40+ instruction types (24 items)
- phase15d: MIR passes — 52 optimization passes in tiered order (25 items)

All 4 tasks include proposals (66-128 lines each).
Order: 15a → 15b → 15c → 15d (sequential)

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**: 35 | **Archived**: 5+
+**Active tasks**: 39 | **Archived**: 5+
 
 ---
 
@@ -158,6 +158,19 @@ Port the type checker (~21K LOC C++) to TML. Highest-risk, longest phase (8 mont
 
 **Order**: 14a → 14b → 14c → 14d (sequential, 14a/14b can partially overlap)
 
+## Phase 15 — IR Pipeline in TML (ERA 1, Phase 3)
+
+Port HIR, THIR, MIR builder, and 52 MIR optimization passes from C++ to TML.
+
+| ID | Task | Status | Priority | Progress |
+|----|------|--------|----------|----------|
+| 15a | [HIR Lowering](phase15a_hir-lowering/) | Planned | P0 | 0/24 |
+| 15b | [THIR Lowering](phase15b_thir-lowering/) | Planned | P0 | 0/16 |
+| 15c | [MIR Builder](phase15c_mir-builder/) | Planned | P0 | 0/24 |
+| 15d | [MIR Passes (52 passes)](phase15d_mir-passes/) | Planned | P0 | 0/25 |
+
+**Order**: 15a → 15b → 15c → 15d (sequential)
+
 ## Research
 
 | ID | Task | Status | Priority | Progress |

.rulebook/tasks/phase15a_hir-lowering/.metadata.json

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

.rulebook/tasks/phase15a_hir-lowering/proposal.md

@@ -0,0 +1,128 @@
+# Proposal: HIR Lowering — Rewrite in TML (Phase 15a)
+
+## Why
+
+HIR (High-level Intermediate Representation) is the essential bridge between the parsed AST and
+the MIR builder. It takes the raw syntax tree and a fully-resolved TypeEnv from the type checker
+(phase14d) and produces a typed, desugared tree where every expression node carries its concrete
+type, all syntactic sugar has been eliminated, and generic functions have been monomorphized into
+concrete specializations. Without HIR, the MIR builder would need to re-implement type resolution,
+desugaring, and monomorphization — the entire point of the pipeline split is that HIR does this
+work once, cleanly, so MIR can focus on control flow and SSA construction.
+
+This phase ports ~15,207 LOC of C++ across 8 source files and 4 serialization files to ~9,900
+lines of TML, completing the first major pass of the ERA 1 compiler port.
+
+## What Changes
+
+Port the following C++ files to TML:
+
+- `compiler/src/hir/hir_builder.cpp` (1,511 LOC) — main HIR builder, entry point
+- `compiler/src/hir/hir_builder_expr.cpp` (1,485 LOC) — expression lowering (largest single file)
+- `compiler/src/hir/hir_builder_stmt.cpp` (433 LOC) — statement lowering
+- `compiler/src/hir/hir_builder_pattern.cpp` (362 LOC) — pattern lowering
+- `compiler/src/hir/hir_pass.cpp` (728 LOC) — HIR optimization passes
+- `compiler/src/hir/hir_pass_inline.cpp` (1,292 LOC) — HIR inlining pass
+- `compiler/src/hir/hir_printer.cpp` (619 LOC) — HIR pretty-printer
+- `compiler/src/hir/hir_expr.cpp` (225 LOC), `hir_pattern.cpp` (142 LOC),
+  `hir_module.cpp` (90 LOC), `hir_stmt.cpp` (76 LOC) — HIR node type definitions
+- `compiler/src/hir/serializer/` (4 files, ~3,561 LOC) — binary serialization for pipeline bridge
+
+New TML modules produced:
+
+- `compiler-tml/src/hir/mod.tml` — module root
+- `compiler-tml/src/hir/expr.tml` — `HirExpr` enum (~40 variants, each carrying resolved type)
+- `compiler-tml/src/hir/stmt.tml` — `HirStmt` enum
+- `compiler-tml/src/hir/pattern.tml` — `HirPattern` enum
+- `compiler-tml/src/hir/module.tml` — `HirModule` struct
+- `compiler-tml/src/hir/builder.tml` — `HirBuilder` struct and `lower_module` entry point
+- `compiler-tml/src/hir/lower_expr.tml` — expression lowering (largest module)
+- `compiler-tml/src/hir/monomorph.tml` — generic instantiation engine
+- `compiler-tml/src/hir/printer.tml` — HIR pretty-printer
+
+## Key Decisions
+
+**HirExpr as enum with resolved types on every node.** Every `HirExpr` variant carries its
+concrete `Type` as a field. This is the central design decision of the HIR: type resolution is
+done once here, and every downstream pass (THIR, MIR, codegen) can read the type directly from
+the node without consulting the TypeEnv. This matches the C++ implementation where `HirExpr`
+nodes carry a `resolved_type` field populated during lowering.
+
+**Monomorphization as a separate pass, not interleaved.** When expression lowering encounters a
+call to `foo[I32](x)`, it does not immediately generate the specialized `foo$I32$` function.
+Instead, it records the instantiation in a queue and lowers the call using the mangled name as
+a placeholder. A separate monomorphization pass then drains the queue, generating each
+specialization exactly once (handling recursive generics by checking the queue before adding).
+This matches the C++ design and avoids infinite recursion on recursive generic types like
+`List[List[T]]`.
+
+**Closure capture analysis generates closure struct types.** When a closure `do(x) expr` is
+encountered, capture analysis walks the body and identifies all free variables. For each closure,
+a synthetic struct type is generated (e.g., `__Closure_42`) with one field per captured variable,
+using the capture mode (ref, value, or move) determined by how the variable is used. The closure
+body is lowered as a separate `HirFunc` with the closure struct as its first parameter. This
+matches the C++ `hir_builder.cpp` approach and produces the struct layout that MIR codegen
+expects.
+
+**Desugaring is exhaustive and irreversible.** After HIR lowering, `for`/`while`/`var` syntax
+does not exist in the output. All `for x in iter` loops become explicit iterator protocol calls
+(`iter.next()` in a loop). All `var` declarations become `let mut`. All `if let Just(x) = e`
+patterns become explicit `when` expressions. Downstream passes never need to handle these sugar
+forms.
+
+## Architecture
+
+```
+compiler-tml/src/hir/
+  mod.tml        -- module root, re-exports HirModule, HirExpr, HirBuilder
+  expr.tml       -- HirExpr enum: Lit, Var, Field, Index, Call, When, Loop, Closure, ...
+  stmt.tml       -- HirStmt enum: Let, Expr, Return, ...
+  pattern.tml    -- HirPattern enum: Wildcard, Bind, Struct, Enum, Tuple, ...
+  module.tml     -- HirModule: List[HirFunc] + List[HirTypeDef] + List[HirImpl]
+  builder.tml    -- HirBuilder + lower_module() entry point
+  lower_expr.tml -- lower_expr(), lower_call(), lower_closure(), lower_when(), ...
+  monomorph.tml  -- MonomorphQueue, drain_queue(), mangle_name()
+  printer.tml    -- print_module(), print_func(), print_expr() for debug output
+```
+
+## Pipeline Integration
+
+After phase15a completes, the pipeline is:
+
+```
+AST + TypeEnv (from phase14d)
+ | phase15a: type resolution, desugaring, capture analysis, monomorphization
+ v
+HirModule  →  THIR lowerer (Phase 15b)
+```
+
+The `HirModule` output is a complete, typed, desugared representation of the source. Every
+expression carries its concrete type. No generic functions remain — only their specializations.
+No syntactic sugar remains. This is what THIR consumes.
+
+## Success Criteria
+
+Differential HIR comparison: run the TML HIR builder on all 1,700+ test files and all stdlib
+modules. Serialize the resulting `HirModule` (using the binary serializer from phase 5) and
+compare field-by-field with the C++ HIR builder output. Zero diffs required before phase 15b
+begins.
+
+## Risk Assessment
+
+High. Monomorphization has well-known edge cases: recursive generics (`List[List[T]]`),
+mutually recursive generic functions, generic types appearing only in associated type positions,
+and trait object erasure (where monomorphization does not apply). The C++ implementation handles
+these via a worklist algorithm with cycle detection; the TML port must replicate this exactly.
+
+Closure capture analysis is also subtle: the capture mode (ref vs value vs move) affects the
+generated closure struct layout and must match what the MIR builder expects. A mismatch here
+produces runtime use-after-free bugs that are difficult to trace.
+
+Plan: implement data types and builder core first, test against simple non-generic modules,
+then add monomorphization and test with generic stdlib modules, then add closure support last.
+
+## Dependencies
+
+- **Requires**: phase14d complete (full TypeEnv with behavior dispatch and coercion annotations)
+- **Blocks**: phase15b (THIR lowerer consumes HirModule)
+- **Blocks**: phase15c (MIR builder HIR→MIR path consumes HirModule directly)

.rulebook/tasks/phase15a_hir-lowering/tasks.md

@@ -0,0 +1,52 @@
+# Tasks: HIR Lowering — Rewrite in TML
+
+**Status**: Planned (0/24)
+**Depends on**: phase14d (type checker complete, TypeEnv available)
+**Blocks**: phase15b (THIR needs HIR output)
+**Duration**: 8–10 weeks
+**Risk**: High — desugaring and monomorphization have subtle semantics
+**C++ reference**: ~15,207 LOC → ~9,900 TML
+
+---
+
+## Phase 1: HIR Data Types (4 items)
+
+- [ ] 1.1 Create `compiler-tml/src/hir/mod.tml` — module root
+- [ ] 1.2 Create `compiler-tml/src/hir/expr.tml` — `HirExpr` enum: all expression variants with resolved types (mirrors hir_expr.hpp, ~40 variants)
+- [ ] 1.3 Create `compiler-tml/src/hir/stmt.tml` — `HirStmt` enum, `compiler-tml/src/hir/pattern.tml` — `HirPattern` enum
+- [ ] 1.4 Create `compiler-tml/src/hir/module.tml` — `HirModule` struct: functions, types, impls, all with resolved type annotations
+
+## Phase 2: HIR Builder Core (6 items)
+
+- [ ] 2.1 Create `compiler-tml/src/hir/builder.tml` — `HirBuilder` struct: TypeEnv ref, current module, monomorphization queue
+- [ ] 2.2 Implement `lower_module(ast: Module, env: ref TypeEnv) -> HirModule` — entry point
+- [ ] 2.3 Implement function lowering: resolve param types, return type, lower body → `HirFunc`
+- [ ] 2.4 Implement struct/enum lowering: resolve field types, compute layout, assign field indices
+- [ ] 2.5 Implement desugaring: `var x = v` → `let mut x = v`, `for x in iter` → loop over iterator protocol
+- [ ] 2.6 Implement closure capture analysis: identify captured variables, determine capture mode (by ref, by value, by move)
+
+## Phase 3: Expression Lowering (5 items)
+
+- [ ] 3.1 Create `compiler-tml/src/hir/lower_expr.tml` — expression lowering
+- [ ] 3.2 Implement literal/variable/field/index expressions — attach resolved types
+- [ ] 3.3 Implement call expressions: resolve callee, lower args, attach return type
+- [ ] 3.4 Implement control flow: lower if/else, when (match), loop — with type-annotated branches
+- [ ] 3.5 Implement closures: create closure struct with captured fields, lower body as separate function
+
+## Phase 4: Monomorphization (4 items)
+
+- [ ] 4.1 Create `compiler-tml/src/hir/monomorph.tml` — generic instantiation engine
+- [ ] 4.2 Implement: when generic function/type is used with concrete types, generate specialized version
+- [ ] 4.3 Implement monomorphization queue: collect all needed instantiations, process iteratively until fixpoint
+- [ ] 4.4 Implement name mangling: `List[I32]` → `List$I32$`, `HashMap[Str, I64]` → `HashMap$Str$I64$`
+
+## Phase 5: HIR Printer + Serialization (3 items)
+
+- [ ] 5.1 Create `compiler-tml/src/hir/printer.tml` — pretty-print HIR for debugging
+- [ ] 5.2 Implement HIR serialization (binary) for hybrid pipeline bridge
+- [ ] 5.3 Test: round-trip HIR through serialize/deserialize, verify identical
+
+## Phase 6: Differential Testing (2 items)
+
+- [ ] 6.1 Lower 20 stdlib modules to HIR → compare with C++ HIR output (field by field)
+- [ ] 6.2 Lower full test suite → verify zero diffs against C++ HIR builder

.rulebook/tasks/phase15b_thir-lowering/.metadata.json

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

.rulebook/tasks/phase15b_thir-lowering/proposal.md

@@ -0,0 +1,121 @@
+# Proposal: THIR Lowering — Rewrite in TML (Phase 15b)
+
+## Why
+
+THIR (Typed High-level Intermediate Representation) is a thin transformation over HIR that
+inserts the remaining implicit semantic content that the parser and type checker left out:
+coercions, concrete method resolution, operator desugaring, and pattern exhaustiveness
+verification. It exists as a distinct pass because these transformations require the full
+TypeEnv (available after phase14d) and the typed HIR (available after phase15a), but they
+must happen before MIR construction, which assumes all method calls are already resolved to
+concrete functions and all operators are already desugared to their trait method equivalents.
+
+Without THIR, the MIR builder would need to re-run method resolution and coercion insertion
+mid-construction, tangling two fundamentally different concerns. The separation is documented
+as a hard invariant from phase12c.
+
+## What Changes
+
+Port the following C++ files to TML:
+
+- `compiler/src/thir/thir_lower.cpp` (1,138 LOC) — main THIR lowering pass
+- `compiler/src/thir/exhaustiveness.cpp` (623 LOC) — pattern exhaustiveness analysis
+- `compiler/src/thir/thir_module.cpp` (112 LOC) — THIR module and node type definitions
+- 6 header files (1,169 LOC combined) — `ThirExpr`, `ThirModule`, `ThirLower`, exhaustiveness
+
+New TML modules produced:
+
+- `compiler-tml/src/thir/mod.tml` — module root
+- `compiler-tml/src/thir/expr.tml` — `ThirExpr` enum extending `HirExpr` with coercion nodes
+- `compiler-tml/src/thir/module.tml` — `ThirModule` struct
+- `compiler-tml/src/thir/lower.tml` — `ThirLower` struct and `lower` entry point
+- `compiler-tml/src/thir/exhaustiveness.tml` — exhaustiveness checker
+
+## Key Decisions
+
+**Coercions as explicit nodes in THIR, not implicit annotations.** When an `I8` value is used
+where `I32` is expected, THIR inserts a `ThirExpr::Coerce { inner, from_ty, to_ty }` node
+wrapping the original expression. Downstream passes (MIR builder) see a concrete coercion
+instruction and generate the appropriate `sext` or `zext` LLVM instruction. Making coercions
+implicit (e.g., via a side table or metadata annotation) would require the MIR builder to
+re-inspect types at every use site — the explicit node model is simpler and matches the C++
+`ThirLower::insert_coercion` design.
+
+**Method resolution uses the trait solver from phase14d, not a local lookup.** When THIR
+encounters `obj.method(args)` in the HIR, it calls the `BehaviorSolver` from phase14d to
+resolve the concrete impl. The result is a `ThirExpr::MethodCall { recv, method_path, args }`
+node where `method_path` is the fully-qualified path to the impl method (e.g.,
+`core::iter::Iterator::next` rather than just `next`). This eliminates all ambiguity before
+MIR construction, which cannot perform method resolution itself.
+
+**Exhaustiveness uses matrix decomposition (usefulness algorithm).** The exhaustiveness
+checker works by constructing a pattern matrix from all `when` arms and computing whether the
+set of patterns is exhaustive via the standard "usefulness" algorithm (the same approach as
+rustc's `check_match`). For each constructor (enum variant, literal range, struct), it expands
+the matrix and checks recursively. This is the algorithm used in `exhaustiveness.cpp` and
+must be replicated rather than approximated — the C++ test suite includes edge cases for
+or-patterns, range patterns, and nested struct patterns that simpler approaches fail on.
+
+**Operator desugaring is finalized here, not in phase14d.** Phase14d partially desugars
+operators via the coercion pass (resolving the trait impl), but THIR rewrites the AST node
+itself. After THIR, no `BinOp(Add, a, b)` nodes exist — only
+`MethodCall(a, "std::ops::Add::add", [b])`. This two-step design is a documented phase12c
+invariant: inference uses the syntactic form, THIR rewrites to the semantic form.
+
+## Architecture
+
+```
+compiler-tml/src/thir/
+  mod.tml            -- module root, re-exports ThirModule, ThirExpr, ThirLower
+  expr.tml           -- ThirExpr enum: all HirExpr variants + Coerce, MethodCall (resolved)
+  module.tml         -- ThirModule: List[ThirFunc] + List[ThirTypeDef]
+  lower.tml          -- ThirLower { solver: ref BehaviorSolver, type_env: ref TypeEnv }
+                     --   lower(hir: HirModule) -> ThirModule
+                     --   lower_expr(), insert_coercion(), resolve_method(), desugar_op()
+  exhaustiveness.tml -- PatternMatrix, is_exhaustive(), find_missing_patterns()
+```
+
+## Pipeline Integration
+
+After phase15b completes, the pipeline is:
+
+```
+HirModule (from phase15a)
+ | phase15b: coercion insertion, method resolution, operator desugaring, exhaustiveness check
+ v
+ThirModule  →  MIR builder THIR path (Phase 15c)
+```
+
+The `ThirModule` output is consumed exclusively by the THIR→MIR builder path in phase15c.
+The HIR→MIR legacy path in phase15c consumes `HirModule` directly and does not use `ThirModule`.
+Both paths must produce equivalent MIR — differential testing in phase15c verifies this.
+
+## Success Criteria
+
+Two-level differential testing:
+
+1. THIR node comparison: lower 20 stdlib modules through the TML THIR pass. Serialize the
+   `ThirModule` and compare field-by-field with C++ THIR output. Zero diffs required on method
+   resolution, coercion insertion, and operator desugaring.
+
+2. Exhaustiveness parity: run the TML exhaustiveness checker on all `when` expressions in the
+   full 1,700+ file test suite. Compare reported exhaustiveness errors and unreachable pattern
+   warnings with C++ output. Zero disagreements required.
+
+## Risk Assessment
+
+Medium. The trait solver (phase14d) already handles the most complex resolution logic. THIR
+wiring is largely mechanical: call the solver, wrap results in THIR nodes, recurse through the
+tree. The main risk is the exhaustiveness checker — matrix decomposition is a well-specified
+algorithm but has many edge cases (or-patterns, guard interaction, range patterns on integers).
+The C++ `exhaustiveness.cpp` (623 LOC) is the reference; implement against it directly.
+
+A secondary risk is coercion double-insertion: phase14d already partially inserts coercions via
+its coercion pass. THIR must detect and skip coercions already inserted rather than wrapping
+them again. The C++ implementation checks for existing `CoercionExpr` nodes before inserting.
+
+## Dependencies
+
+- **Requires**: phase15a complete (HirModule is the input to THIR lowering)
+- **Requires**: phase14d complete (BehaviorSolver is called during method resolution)
+- **Blocks**: phase15c (MIR builder THIR path consumes ThirModule)

.rulebook/tasks/phase15b_thir-lowering/tasks.md

@@ -0,0 +1,38 @@
+# Tasks: THIR Lowering — Rewrite in TML
+
+**Status**: Planned (0/16)
+**Depends on**: phase15a (HIR output available)
+**Blocks**: phase15c (MIR builder needs THIR)
+**Duration**: 3–4 weeks
+**Risk**: Medium — thin pass, most complexity already handled by type checker (phase14d)
+**C++ reference**: ~3,042 LOC → ~2,000 TML
+
+---
+
+## Phase 1: THIR Data Types (3 items)
+
+- [ ] 1.1 Create `compiler-tml/src/thir/mod.tml` — module root
+- [ ] 1.2 Create `compiler-tml/src/thir/expr.tml` — `ThirExpr` enum: HIR expressions + coercion nodes + resolved method calls
+- [ ] 1.3 Create `compiler-tml/src/thir/module.tml` — `ThirModule` struct
+
+## Phase 2: THIR Lowering Pass (6 items)
+
+- [ ] 2.1 Create `compiler-tml/src/thir/lower.tml` — `ThirLower` struct and `lower(hir: HirModule) -> ThirModule` entry point
+- [ ] 2.2 Implement coercion insertion: insert implicit type conversions (integer widening, ref coercion, deref coercion)
+- [ ] 2.3 Implement method resolution: resolve `obj.method()` to concrete impl method via trait solver
+- [ ] 2.4 Implement operator desugaring: `a + b` → `a.add(b)`, `a[i]` → `a.index(i)`, `a == b` → `a.eq(b)`
+- [ ] 2.5 Implement associated type normalization: replace `<T as Iterator>::Item` with concrete type
+- [ ] 2.6 Implement `when` arm processing: lower each arm pattern + guard + body
+
+## Phase 3: Exhaustiveness Checker (4 items)
+
+- [ ] 3.1 Create `compiler-tml/src/thir/exhaustiveness.tml` — pattern exhaustiveness analysis
+- [ ] 3.2 Implement: for each `when` expression, compute whether all possible values are covered
+- [ ] 3.3 Implement: enum exhaustiveness — all variants present, or wildcard covers remainder
+- [ ] 3.4 Implement: emit warning for unreachable patterns, error for non-exhaustive match
+
+## Phase 4: Differential Testing (3 items)
+
+- [ ] 4.1 Lower 20 stdlib modules through HIR→THIR → compare with C++ THIR output
+- [ ] 4.2 Lower full test suite → verify zero diffs against C++ THIR lowerer
+- [ ] 4.3 Specifically test: operator desugaring, coercion insertion, exhaustiveness on 10 edge-case files