Architecture Overview & Conformance

Relevant source files

The following files were used as context for generating this wiki page:

• architecture/README.md
• architecture/19-architecture-conformance-and-regression-policy.md
• AGENTS.md
• CONTRIBUTING.md
• README.md
• architecture/decisions/0018-rust-workspace-and-crate-boundaries.md
• crates/tools/architecture-tests/src/tests.rs

Pop Lang is an architecture-first project where documentation serves as a binding, evolvable contract for the entire system. The project strictly enforces a hierarchy of authority where the latest accepted Architecture Decision Records (ADRs) and integrated architecture documents override implementation convenience or existing code. This ensures the language maintains its identity as a native, strongly and statically typed extension of the Luau syntax while preventing "Lua regressions"—the accidental reintroduction of dynamic, table-centered semantics.

The core architectural mission is to provide a zero-cost abstraction model through a backend-neutral semantic pipeline. This pipeline transitions from source code to High-level Intermediate Representation (HIR) and then to Canonical Mid-level Intermediate Representation (MIR), ensuring that language semantics remain identical across LLVM, interpreters, and future virtual machine backends.

Sources: architecture/README.md:1-25, architecture/19-architecture-conformance-and-regression-policy.md:3-15, AGENTS.md:15-30

Core Architectural Invariants

Pop Lang is governed by several non-negotiable invariants that define its technical boundaries and identity.

Language Identity and Static Typing

Every runtime value and operation in Pop Lang must have a compiler-proven type. The project explicitly forbids dynamic escape hatches such as Any, Dynamic, or unchecked member lookups. While the syntax is Luau-shaped to maintain readability and low ceremony, the underlying machinery is strictly static.

Sources: architecture/README.md:46-55, AGENTS.md:183-205, README.md:144-155

Structural Hierarchy

Code ownership and visibility follow a fixed hierarchy that determines how units of code are compiled and linked:

1. Item: Individual declarations (members, functions, etc.).
2. Module: A single .pop file, forming the private visibility boundary.
3. Bubble: The independent unit of compilation and linking; forms the internal visibility boundary.
4. Package: A versioned, publishable directory containing a bubble.toml.
5. Workspace: A root directory grouping packages with a shared bubble.lock.

Sources: architecture/README.md:92-100, AGENTS.md:295-315

The Semantic Pipeline

The compiler architecture requires a strict, multi-stage pipeline to ensure backend neutrality.

Conformance and Regression Policy

The Conformance and Regression Policy defines what constitutes a bug at the architectural level. An implementation that contradicts accepted architecture is considered buggy, even if it functions correctly in isolation.

Classification of Architectural Defects

Bug Class	Description	Examples
Architecture Drift	Code or APIs that bypass required boundaries or invariants.	HIR containing LLVM-specific types; public APIs returning untyped values.
Architecture Gap	Public behavior implemented without a supporting ADR or design.	Adding weak references without defined reachability semantics.
Backend Drift	Semantic disagreement between backends (e.g., LLVM vs. Interpreter).	Different observable behavior for numeric overflow between backends.
Lua Regression	Reintroducing Lua's table-centered or dynamic semantics.	Using tables for records; implementing classes via metatables.

Sources: architecture/19-architecture-conformance-and-regression-policy.md:46-95, AGENTS.md:215-225

Mandatory Task Loop

All development must follow a specific sequence to maintain conformance. This is primarily enforced through the "Architecture → Tests → Implementation" workflow.

Implementation Boundaries (Rust Workspace)

The toolchain is implemented in Rust (edition 2024). To prevent architectural leakage, the repository uses a virtual Cargo workspace with strictly enforced crate boundaries.

Crate Inventory and Dependency Rules

• crates/compiler/: Contains individual crates for syntax, resolution, types, HIR, and MIR.
• crates/runtime/: Partitioned into interface (PLRI), collector (GC), and native (ABI).
• Forbidden Dependencies: Portable compiler crates (like hir or mir) are forbidden from depending on backend implementations (like llvm) to preserve neutrality.

Sources: architecture/decisions/0018-rust-workspace-and-crate-boundaries.md:1-40, crates/tools/architecture-tests/src/tests.rs:10-50

Automated Architecture Testing

The project includes a specialized test suite (pop-architecture-tests) that validates the workspace structure.

#[test]
fn portable_crates_do_not_name_backend_packages() {
    // Verifies that crates like hir/mir/types do not depend on pop-backend-llvm
    // Derived from crates/tools/architecture-tests/src/tests.rs
}

Sources: crates/tools/architecture-tests/src/tests.rs:260-290

Conclusion

Architecture in Pop Lang is not a suggestion but the primary project contract. By prioritizing deterministic, statically typed behavior and enforcing strict IR boundaries, the project ensures long-term portability and maintainability. Every contribution must verify that it does not introduce "Lua regressions" and that it adheres to the "Architecture-to-test-to-implementation" workflow. This rigorous approach guarantees that Pop Lang remains a distinct, high-performance native language while retaining the ergonomics of Luau.

Sources: architecture/19-architecture-conformance-and-regression-policy.md:240-250, AGENTS.md:450-465