MIR Reference Interpreter
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The MIR (Medium-level Intermediate Representation) Reference Interpreter is a core backend component of the Pop Lang compiler. Its primary purpose is to provide a reference execution environment for verified MIR Bubbles without requiring native code generation via LLVM. This allows for rapid testing, validation of language semantics, and differential testing against native backends to ensure consistency across the compiler pipeline.
Operating as a toolchain-internal utility, the interpreter consumes backend-neutral MIR and executes it using a portable runtime adapter. It is a critical part of Milestone 2 in the project's implementation roadmap, ensuring that core language features—such as control flow, function calls, and error handling—can be exercised and verified early in the development lifecycle.
Sources: architecture/03-compiler-pipeline.md:10-14, architecture/07-implementation-roadmap.md:38-42
Architectural Position
The interpreter occupies a unique position in the compiler pipeline, acting as an alternative to the LLVM and experimental C backends. It consumes "Optimized MIR" and interacts with the Pop Lang Runtime Interface (PLRI) to manage execution state.
The diagram shows how the MIR Interpreter serves as a verification tool alongside the primary native compilation path.
Sources: architecture/03-compiler-pipeline.md:5-15, architecture/11-compiler-component-architecture.md:12-32
Core Functionality
MIR Execution
The interpreter executes MIR in its canonical form, which includes explicit control-flow graphs (CFG), block arguments, and explicit failure/cleanup edges. It is responsible for handling:
- Control Flow: Navigating through basic blocks based on conditional branches and direct jumps.
- Function Calls: Managing the call stack and resolving symbol identities across Bubble boundaries.
- Scoped Cleanup: Executing last-in, first-out (LIFO) cleanup blocks when control leaves lexical scopes due to returns, failures, or panics.
Sources: architecture/07-implementation-roadmap.md:38-42, architecture/decisions/0052-typed-results-errors-and-scoped-cleanup.md:52-65
Runtime Integration
The interpreter relies on a minimal runtime adapter to bridge MIR operations with the host system. Key integration points include:
- Memory Management: Interacting with the portable collector for object allocation and tracking managed roots.
- Error Handling: Interpreting
resultIsOk,resultGetOk, andresultGetErroroperations defined in ADR 0052. - Bootstrap GC: Utilizing a "stop-the-world" garbage collector during early milestones to manage heap safety.
Sources: architecture/07-implementation-roadmap.md:46-51, architecture/decisions/0052-typed-results-errors-and-scoped-cleanup.md:52-65
Execution Model and Diagnostics
The interpreter follows a strict "fail-closed" model for verification. If the MIR violates language invariants—such as accessing uninitialized memory or encountering an unverified IR state—the interpreter halts and reports a structured diagnostic.
| Component | Responsibility |
|---|---|
| MIR Verifier | Ensures MIR is well-formed before execution. |
| Stack Manager | Handles local variable storage and block argument passing. |
| Symbol Resolver | Maps SymbolIdentity (BubbleId + SymbolId) to executable MIR bodies. |
| Cleanup Engine | Manages the CleanupScopeId stack to ensure deterministic resource disposal. |
Sources: architecture/11-compiler-component-architecture.md:105-115, architecture/decisions/0052-typed-results-errors-and-scoped-cleanup.md:67-78
Implementation Constraints
As a reference implementation, the interpreter must adhere to several persistent project invariants:
- Backend Neutrality: It must not contain LLVM-specific opcodes or target-specific memory layouts.
- No Dynamic Escape Hatches: It cannot implement dynamic fallback lookup; every operation must be statically typed and resolved in MIR.
- Deterministic Execution: Compile-time execution via the interpreter must be budgeted (fuel/allocation limits) and isolated from ambient host state (no network or filesystem I/O).
Sources: AGENTS.md:35-42, architecture/11-compiler-component-architecture.md:80-90
Conclusion
The MIR Reference Interpreter is essential for establishing the semantic baseline of Pop Lang. By providing a controlled environment to execute portable MIR, it enables the validation of complex language features like typed result propagation and precise GC before they are committed to native machine code.
Sources: architecture/07-implementation-roadmap.md:40-42, architecture/19-architecture-conformance-and-regression-policy.md:35-40