Backend Contract & Capabilities
Relevant source files
The following files were used as context for generating this wiki page:
- AGENTS.md
- architecture/19-architecture-conformance-and-regression-policy.md
- architecture/22.6-standard-library-implementation-plan.md
- crates/compiler/documentation/src/lib.rs
- architecture/decisions/0028-toolchain-distribution-and-popup-management.md
- architecture/decisions/0032-concise-apis-and-cost-contracts.md
- crates/tools/architecture-tests/src/tests.rs
The Pop Lang backend architecture is defined by a strict contract that ensures semantic equivalence across diverse execution strategies, including LLVM, a MIR interpreter, and a future VM. Every backend is required to consume verified, backend-neutral Mid-level Intermediate Representation (MIR) and adhere to the versioned Pop Lang Runtime Interface (PLRI). This design prevents backend-specific leakage into the language's core semantic model and ensures that program behavior remains deterministic regardless of the target platform.
Sources: AGENTS.md:65-67, architecture/19-architecture-conformance-and-regression-policy.md:55-58
Semantic Equivalence and MIR Ownership
Pop Lang maintains a backend-neutral Middle Intermediate Representation (MIR) which serves as the ultimate semantic contract for all execution targets. Backends are prohibited from calling back into earlier stages of the pipeline, such as parsing, resolution, or typing.
Backend-Neutral IR Pipeline
The compilation pipeline enforces a strict one-way flow where the backend is the final consumer of typed and verified representations.
The diagram shows the required semantic pipeline where HIR and MIR remain neutral and backends are isolated from front-end logic.
Sources: AGENTS.md:278-290, architecture/19-architecture-conformance-and-regression-policy.md:12-16
Backend Drift
BackendDrift is classified as a bug where the LLVM backend, MIR interpreter, or VM produce different observable semantics. The only permitted exceptions are documented target-specific capabilities (e.g., bit-width differences or platform-specific hardware access).
Sources: architecture/19-architecture-conformance-and-regression-policy.md:55-58
The Pop Lang Runtime Interface (PLRI)
Generated code interacts with runtime services exclusively through the versioned, backend-neutral PLRI. This interface governs memory management, object initialization, and garbage collection (GC) proof obligations.
PLRI Core Capabilities
| Capability | Description | Verification Requirement |
|---|---|---|
| GC Model | Precise concurrent generational collector with a moving nursery. | Must preserve precise roots and stack maps across all backends. |
| Object Identity | Native runtime object representations. | No hidden table/metatable lookup; direct layout access. |
| Error Handling | Typed Result propagation and panic conditions. | Backends must implement LIFO cleanup and exhaustive boundary checks. |
| Async/Tasks | Structured concurrency via Task, Channel, and Actor. | Deterministic scheduler and backpressure management. |
Sources: AGENTS.md:315-322, architecture/19-architecture-conformance-and-regression-policy.md:100-110, architecture/22.6-standard-library-implementation-plan.md:15-20
Relocation and GC Contract
Backends must conform to the RelocationConformance contract, specifically supporting multiple stages of relocation to ensure memory safety during GC cycles.
This diagram illustrates the interaction between the backend and the runtime interface during a garbage collection relocation event.
Sources: crates/tools/architecture-tests/src/tests.rs:360-370, AGENTS.md:315-322
Target Capabilities and Validation
Backends are validated against a "Runtime Profile" that describes their specific execution characteristics and limitations.
Runtime Profile Factors
The backend-api enforces specific runtime profile facts that backends must declare:
- Managed References: Whether the backend supports relocating managed references.
- ABI Compatibility: Validation of native ABI against
IncompatibleNativeAbierrors. - GC Capability: Specific collector features supported (e.g., concurrent vs. stop-the-world).
Sources: crates/tools/architecture-tests/src/tests.rs:480-490
Cost Contracts
Backends must respect explicit "Cost Contracts" documented in the standard library. If an API is documented as allocation-free or of a specific complexity (e.g., O(1)), the backend implementation must ensure these bounds are not violated through hidden work.
| Tag | Backend Responsibility |
|---|---|
<allocation> | Ensure no nursery or heap allocations are generated. |
<complexity> | Preserve documented asymptotic bounds (e.g., time="O(n)"). |
<effect> | Check kind (e.g., Blocks, Suspends, Unsafe) against backend behavior. |
Sources: crates/compiler/documentation/src/lib.rs:250-265, architecture/decisions/0032-concise-apis-and-cost-contracts.md:12-18
Toolchain Distribution and Host Support
The backend environment is managed by popup, a toolchain manager that ensures immutable, verified, and relocatable distributions.
Distribution Components
A toolchain distribution includes:
- The
popcompiler and first-party tools. - The versioned PLRI implementation.
- Target adapters and linker support files.
- Foundational Bubbles (
Pop.InternalandPop.Standard).
Sources: architecture/decisions/0028-toolchain-distribution-and-popup-management.md:50-65
Host Matrix Validation
Backends are only considered supported if they pass a complete installation smoke test on a specific host target. This includes verifying:
- Compiler check functionality.
- Native/Runtime execution.
- Foundational Bubble loading.
- Diagnostic rendering outside the source checkout.
Sources: architecture/decisions/0028-toolchain-distribution-and-popup-management.md:270-280
Conclusion
The Backend Contract in Pop Lang ensures that execution is a deterministic projection of MIR. By mandating backend neutrality for intermediate representations and enforcing a precise runtime interface (PLRI), the architecture guarantees that developers can rely on consistent behavior and performance costs regardless of whether they target a native binary via LLVM or a sandboxed environment via a virtual machine. This contract is the primary defense against "Lua regressions" where dynamic fallback behavior might otherwise leak into native execution.
Sources: AGENTS.md:323-326, architecture/19-architecture-conformance-and-regression-policy.md:70-75