Compiler Architecture Best Practices
9 sections
Overview
Implement verified industry best practices and documented aspirational patterns as enforceable rules with supporting infrastructure, creating the foundational correctness-enforcement layer that ALL downstream plans build on. This plan closes 6 confirmed gaps surfaced by a dual-source (Codex + Gemini) TPR review against 10 reference compilers (Rust, Go, TypeScript, Zig, Swift, Gleam, Roc, Elm, Koka, Lean 4), plus 3 aspirational patterns already documented in impl-hygiene.md §Aspirational Patterns. Effort is not a constraint — this is about building the best possible architectural foundation.
Planned
9 sections
Foundation & Policy Rules
Establish shared policy rules that all subsequent sections reference — compile-time performance gates, crash regression test discipline, and explicit phase documentation
AST/IR Immutability Contract
Explicitly document the AST/IR immutability invariant in rule files — the type-system enforcement already exists, this section makes it an auditable rule
Type Solver Budget Infrastructure
Add fuel counters and depth limits to the type solver so pathological generics terminate predictably with structured diagnostics instead of stack overflow or nontermination
Diagnostic Ordering & Suppression
Upgrade diagnostic dedup to (error_code, span), add child-span TyError suppression, and ensure deterministic cross-file ordering so diagnostic snapshots are stable
Incremental Edit-Sequence Testing
Expand the existing revision test infrastructure into multi-step edit-sequence testing that validates Salsa cache invalidation correctness — new Salsa-touching changes require revision tests
Cross-Target Codegen Verification
Mandate and implement FileCheck-based ABI assertions for non-host targets so ABI/layout/calling-convention changes are verified beyond the host architecture
TypeFolder Trait
Extract the shared type-transformation recursion skeleton from 4+ substitution implementations into a TypeFolder trait, eliminating algorithmic duplication (impl-hygiene LEAK)
Packed Symbol Representation
Design and implement a Symbol = (ModuleId, Name) type that encodes module provenance alongside identifier identity, enabling O(1) cross-module resolution without secondary lookups
Layout Caching via Salsa Query
Extract type layout computation from ori_repr's imperative pass into a Salsa-tracked layout_of(Idx) -> Layout query, replacing the manual RefCell<FxHashMap> cache with demand-driven memoization