chore(tasks): Phase 14 type checker tasks — 4 tasks, 90 items, CRITICAL PATH

ERA 1, Phase 2: Port type checker from C++ (~21K LOC) to TML (~13.6K LOC):
- phase14a: Type registration — Type repr, TypeEnv, builtins, AST walk (22 items)
- phase14b: Module resolution — imports, visibility, re-exports, binary cache (20 items)
- phase14c: Type inference — Hindley-Milner, unification, call resolution (26 items)
- phase14d: Behavior dispatch — trait solver, coherence, coercion insertion (22 items)

All 4 tasks include real proposals (67-141 lines each).
Dependency: 14a → 14b → 14c → 14d (sequential, 14a/14b partially overlap)

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**: 31 | **Archived**: 5+
+**Active tasks**: 35 | **Archived**: 5+
 
 ---
 
@@ -145,6 +145,19 @@ Port lexer and parser from C++ to TML — first compiler subsystems in TML.
 
 **Order**: 13a → 13b → 13c → 13d (sequential)
 
+## Phase 14 — Type Checker in TML (ERA 1, Phase 2) ⚠️ CRITICAL PATH
+
+Port the type checker (~21K LOC C++) to TML. Highest-risk, longest phase (8 months). See [invariant doc](phase12c_typechecker-invariants/).
+
+| ID | Task | Status | Priority | Progress |
+|----|------|--------|----------|----------|
+| 14a | [Type Registration](phase14a_typechecker-registration/) | Planned | P0 | 0/22 |
+| 14b | [Module Resolution](phase14b_typechecker-module-resolution/) | Planned | P0 | 0/20 |
+| 14c | [Type Inference](phase14c_typechecker-inference/) | Planned | P0 | 0/26 |
+| 14d | [Behavior Dispatch](phase14d_typechecker-behavior-dispatch/) | Planned | P0 | 0/22 |
+
+**Order**: 14a → 14b → 14c → 14d (sequential, 14a/14b can partially overlap)
+
 ## Research
 
 | ID | Task | Status | Priority | Progress |

.rulebook/tasks/phase14a_typechecker-registration/.metadata.json

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

.rulebook/tasks/phase14a_typechecker-registration/proposal.md

@@ -0,0 +1,67 @@
+# Proposal: Type Checker — Type Registration (Sub-phase 2a)
+
+## Problem
+
+The TML type checker's first phase populates `TypeEnv` with all type declarations before any
+inference or checking begins. This phase is currently implemented in C++ across `type.cpp` (965
+LOC), `env_core.cpp`, `env_definitions.cpp`, `env_scope.cpp`, `builtins_cache.cpp`, and ten
+`builtins/*.cpp` files (~5,302 LOC total). Porting this phase to TML is the entry point for
+self-hosting the type checker and unblocks all subsequent checking sub-phases (14b–14d).
+
+## Solution
+
+Port the type representation and environment initialization code to four TML modules under
+`compiler-tml/src/types/`:
+
+- `type.tml` — `Type` as a TML enum replacing the C++ class hierarchy in `type.hpp`
+- `env.tml` — `TypeEnv` struct replacing `TypeEnv` fields and methods from `env.hpp`
+- `builtins.tml` — builtin type/behavior registration replacing `builtins/*.cpp`
+- `register.tml` — AST declaration walker replacing `env_definitions.cpp` and checker `core.cpp`
+  phase-1 logic
+
+## Key Design Decisions
+
+**Type as enum, not class hierarchy.** The C++ code uses a `Type` base class with ~15 derived
+classes. TML enums with payload variants express the same structure more concisely and enable
+exhaustive `when` matching throughout the checker, eliminating virtual dispatch and downcasts.
+
+**HashMap-backed TypeEnv.** `TypeEnv` holds three `HashMap[Str, ...]` maps (types, functions,
+behaviors). Lookup is O(1) average. The C++ implementation uses `std::unordered_map` with the
+same semantics, so the port is direct.
+
+**Scope chain via List[Scope].** Each `Scope` holds a `Maybe[ref Scope]` parent pointer and a
+local `HashMap[Str, Type]`. `lookup` walks the chain from innermost scope to module root. This
+matches the C++ `env_scope.cpp` algorithm exactly.
+
+**Builtin registration at env construction.** `TypeEnv.new()` calls `register_builtins(self)`
+immediately, matching `env_core.cpp`'s constructor behavior. All 14 primitives, 13 behaviors,
+5 memory types, and 4 collection types are registered before any user code is processed.
+
+**Generic substitution in-tree.** `Type.substitute(params)` performs deep substitution on
+`Type::Generic` variants, enabling monomorphization without a separate pass. This replaces the
+C++ `type.cpp` `substitute` method.
+
+## Files Changed
+
+| File | Purpose |
+|------|---------|
+| `compiler-tml/src/types/type.tml` | Type enum, equality, display, substitution, size/align |
+| `compiler-tml/src/types/env.tml` | TypeEnv struct, Scope, register/lookup operations |
+| `compiler-tml/src/types/builtins.tml` | All builtin type and behavior registration |
+| `compiler-tml/src/types/register.tml` | AST declaration walker — structs, enums, functions |
+
+## Success Criteria
+
+Differential testing: serialize the TML `TypeEnv` after registration and compare field-by-field
+with C++ `TypeEnv` output on the same input. Zero differences on all 20 stdlib modules and the
+full test suite constitutes a passing port. The C++ registration phase remains the reference
+until phase14d completes.
+
+## Dependencies
+
+- **Requires**: phase13d (TML frontend parsed and AST available in TML), phase12c (type system
+  invariant document for correctness reference)
+- **Blocks**: phase14b (module resolution reads the populated TypeEnv to resolve imports)
+- **Duration**: 6–8 weeks
+- **Risk**: Medium — type representation and builtin registration are well-scoped with no
+  constraint solving or inference logic in scope

.rulebook/tasks/phase14a_typechecker-registration/tasks.md

@@ -0,0 +1,47 @@
+# Tasks: Type Checker — Type Registration (Sub-phase 2a)
+
+**Status**: Planned (0/22)
+**Depends on**: phase13d (TML frontend integrated), phase12c (invariant document)
+**Blocks**: phase14b (module resolution needs TypeEnv populated)
+**Duration**: 6–8 weeks
+**Risk**: Medium — well-scoped, no inference yet
+**C++ reference**: ~5,302 LOC → ~3,400 TML
+
+---
+
+## Phase 1: Type Representation (6 items)
+
+- [ ] 1.1 Create `compiler-tml/src/types/type.tml` — `Type` enum: Primitive, Struct, Enum, Func, Generic, Ref, Ptr, Array, Tuple, Never, Unit, Unknown
+- [ ] 1.2 Implement type equality: `Type.equals(other: Type) -> Bool` with structural comparison
+- [ ] 1.3 Implement type display: `Type.to_str() -> Str` for error messages
+- [ ] 1.4 Implement generic type substitution: `Type.substitute(params: HashMap[Str, Type]) -> Type`
+- [ ] 1.5 Implement type size/alignment calculation: `Type.size() -> I64`, `Type.align() -> I64`
+- [ ] 1.6 Test: round-trip all Type variants through serialize/deserialize
+
+## Phase 2: TypeEnv Core (5 items)
+
+- [ ] 2.1 Create `compiler-tml/src/types/env.tml` — `TypeEnv` struct: types (HashMap), functions (HashMap), behaviors (HashMap), scopes (List[Scope])
+- [ ] 2.2 Implement `Scope` type: parent scope ref, local bindings, scope kind (Module/Function/Block)
+- [ ] 2.3 Implement `TypeEnv.register_type(name: Str, ty: Type)` — add to types map, error on duplicate
+- [ ] 2.4 Implement `TypeEnv.register_function(name: Str, sig: FuncSig)` — add to functions map
+- [ ] 2.5 Implement `TypeEnv.push_scope()`, `pop_scope()`, `lookup(name: Str) -> Maybe[Type]` with scope chain
+
+## Phase 3: Builtin Types (5 items)
+
+- [ ] 3.1 Create `compiler-tml/src/types/builtins.tml` — register all primitive types: I8, I16, I32, I64, U8, U16, U32, U64, F32, F64, Bool, Str, Unit, Never
+- [ ] 3.2 Register builtin behaviors: Add, Sub, Mul, Div, Eq, Ord, Hash, Display, Debug, Clone, Copy, Drop, Iterator
+- [ ] 3.3 Register memory builtins: Heap[T], Shared[T], Sync[T], Weak[T], RawPtr
+- [ ] 3.4 Register collection builtins: List[T], HashMap[K,V], Maybe[T], Outcome[T,E]
+- [ ] 3.5 Test: TypeEnv after builtin registration has all expected types and behaviors
+
+## Phase 4: Declaration Registration from AST (4 items)
+
+- [ ] 4.1 Create `compiler-tml/src/types/register.tml` — walk AST Module, register all declarations
+- [ ] 4.2 Implement struct registration: extract fields, generic params, where clauses → register Type::Struct
+- [ ] 4.3 Implement enum registration: extract variants with payload types → register Type::Enum
+- [ ] 4.4 Implement function registration: extract params, return type, generic params → register FuncSig
+
+## Phase 5: Differential Testing (2 items)
+
+- [ ] 5.1 Register types from 20 stdlib modules → serialize TypeEnv → compare with C++ TypeEnv output
+- [ ] 5.2 Register types from full test suite → verify zero diffs against C++ registration phase

.rulebook/tasks/phase14b_typechecker-module-resolution/.metadata.json

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

.rulebook/tasks/phase14b_typechecker-module-resolution/proposal.md

@@ -0,0 +1,74 @@
+# Proposal: Type Checker — Module Resolution (Sub-phase 2b)
+
+## Problem
+
+Before the type checker can check any expression, it must resolve all `use` imports and make
+the declared types visible in the correct scopes. This is the second phase of checking in the
+C++ compiler, spanning `env_module_loading.cpp` (875 LOC), `env_module_load.cpp` (508 LOC),
+`env_module_load_decls.cpp` (1,253 LOC), `module.cpp` (549 LOC), `module_metadata.cpp` (740
+LOC), `module_binary.cpp` (799 LOC), and `module_binary_read.cpp` (1,409 LOC) — ~7,211 LOC
+total. Until this phase is ported to TML, the self-hosted type checker cannot process any
+multi-file program.
+
+## Solution
+
+Port module resolution to four TML modules under `compiler-tml/src/types/`:
+
+- `module.tml` — `Module` struct and `ModulePath`, `Visibility`, `ModuleMetadata` types
+- `imports.tml` — `use` statement resolver covering single, glob, renamed, and re-export forms
+- `module_loader.tml` — file-system search, load-parse-register pipeline, circular import guard
+- `module_binary.tml` — binary serialization and cache read/write for incremental compilation
+
+## Key Design Decisions
+
+**Module path as List[Str].** `std::collections::HashMap` is represented as
+`List["std", "collections", "HashMap"]`. Display joins with `"::"`. This is simpler than a
+custom struct and integrates cleanly with `HashMap[ModulePath, Module]` keyed lookups.
+
+**File-system-based module search.** Given `use std::json`, the loader searches `lib/std/src/json/mod.tml`
+and `lib/std/src/json.tml` in order, matching the C++ `env_module_loading.cpp` search algorithm.
+The search roots are passed in at loader construction time, making the loader testable without
+touching the real filesystem.
+
+**Circular import detection via loading stack.** The loader maintains a `List[ModulePath]` of
+modules currently being loaded. Before loading a module, it checks whether the path is already
+in this stack. If so, it emits a `E0201: circular import` diagnostic and returns an error. This
+matches the C++ `loading_stack_` guard in `env_module_loading.cpp`.
+
+**Binary cache for incremental compilation.** Each resolved module serializes to a compact
+binary format (header + fingerprint + declaration table). On reload, the loader reads the
+fingerprint, compares with the source file hash, and skips re-parsing if unchanged. The format
+is identical to the C++ `module_binary.cpp` output so cached modules produced by C++ can be
+read by the TML loader during the transition period.
+
+**Re-export propagation.** `pub use inner::Type` adds the item to the current module's public
+visibility map. When another module imports the current module, the resolver checks this map
+and registers the re-exported item under the importer's scope. This matches the two-pass
+approach in `env_module_load.cpp` (collect re-exports first, then resolve importers).
+
+## Files Changed
+
+| File | Purpose |
+|------|---------|
+| `compiler-tml/src/types/module.tml` | Module struct, ModulePath, Visibility, ModuleMetadata |
+| `compiler-tml/src/types/imports.tml` | use statement resolution — single, glob, renamed, pub use |
+| `compiler-tml/src/types/module_loader.tml` | File search, load-parse-register, circular import guard |
+| `compiler-tml/src/types/module_binary.tml` | Binary cache serialize/deserialize, fingerprinting |
+
+## Success Criteria
+
+Differential testing: run import resolution on 20 stdlib modules and compare the resulting
+`TypeEnv` (all registered names, their types, and visibility) against C++ output on the same
+inputs. Zero differences on stdlib and the full test suite constitutes a passing port. The C++
+resolver remains the reference until phase14d completes.
+
+## Dependencies
+
+- **Requires**: phase14a (TypeEnv must be populated with builtin types and declaration skeletons
+  before imports can be resolved against it)
+- **Blocks**: phase14c (Hindley-Milner inference walks import-resolved TypeEnv to infer
+  expression types — unresolved imports produce spurious type errors)
+- **Duration**: 4–6 weeks
+- **Risk**: Medium — the algorithm is a well-defined graph traversal with no constraint solving;
+  the main complexity is the binary cache format compatibility requirement during the C++/TML
+  transition period

.rulebook/tasks/phase14b_typechecker-module-resolution/tasks.md

@@ -0,0 +1,45 @@
+# Tasks: Type Checker — Module Resolution (Sub-phase 2b)
+
+**Status**: Planned (0/20)
+**Depends on**: phase14a (TypeEnv populated with declarations)
+**Blocks**: phase14c (inference needs resolved imports)
+**Duration**: 4–6 weeks
+**Risk**: Medium — mechanical graph traversal, well-defined algorithm
+**C++ reference**: ~7,211 LOC → ~4,700 TML
+
+---
+
+## Phase 1: Module Representation (4 items)
+
+- [ ] 1.1 Create `compiler-tml/src/types/module.tml` — `Module` struct: name, path, declarations, imports, visibility map, metadata
+- [ ] 1.2 Implement `ModulePath` type: `List[Str]` with display as `"std::collections::HashMap"`
+- [ ] 1.3 Implement `Visibility` checking: pub, pub(crate), private — resolve against module tree
+- [ ] 1.4 Implement `ModuleMetadata`: file path, last modified, fingerprint for incremental
+
+## Phase 2: Import Resolution (5 items)
+
+- [ ] 2.1 Create `compiler-tml/src/types/imports.tml` — `use` statement resolver
+- [ ] 2.2 Implement single import: `use std::collections::HashMap` → resolve path, register alias in scope
+- [ ] 2.3 Implement glob import: `use std::collections::*` → resolve all pub items, register each
+- [ ] 2.4 Implement renamed import: `use std::collections::HashMap as Map` → register under alias
+- [ ] 2.5 Implement re-export: `pub use inner::Type` → make visible to importers of this module
+
+## Phase 3: Module Loading (5 items)
+
+- [ ] 3.1 Create `compiler-tml/src/types/module_loader.tml` — load module from file path, parse, register
+- [ ] 3.2 Implement module search: given `use std::json`, find `lib/std/src/json/mod.tml`
+- [ ] 3.3 Implement circular import detection: track loading stack, error on cycle
+- [ ] 3.4 Implement declaration loading: walk loaded module AST, register types/functions into TypeEnv
+- [ ] 3.5 Implement transitive import resolution: if A imports B imports C, A sees B's pub re-exports
+
+## Phase 4: Module Binary Cache (4 items)
+
+- [ ] 4.1 Create `compiler-tml/src/types/module_binary.tml` — serialize resolved module to binary cache
+- [ ] 4.2 Implement module fingerprinting: hash(source content) for cache invalidation
+- [ ] 4.3 Implement cache read: load previously resolved module from binary, skip re-parsing
+- [ ] 4.4 Implement cache invalidation: source changed or dependency changed → re-resolve
+
+## Phase 5: Differential Testing (2 items)
+
+- [ ] 5.1 Resolve imports for 20 stdlib modules → compare resolved TypeEnv with C++ output
+- [ ] 5.2 Resolve imports for full test suite → verify zero diffs against C++ module resolution

.rulebook/tasks/phase14c_typechecker-inference/.metadata.json

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