Language Philosophy & Principles

Relevant source files

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

• architecture/01-vision-and-principles.md
• README.md
• architecture/09-relationship-to-luau.md
• architecture/19-architecture-conformance-and-regression-policy.md
• AGENTS.md
• architecture/decisions/0032-concise-apis-and-cost-contracts.md

Pop Lang is a native, strongly and statically typed programming language designed to grow beyond the table-centered foundations of Lua. While heavily inspired by the lightweight syntax and ergonomics of Luau, Pop Lang prioritizes explicit semantics, static guarantees, and native performance without relying on a dynamic fallback. It is built as an architecture-first project where documentation and principles serve as the binding contract for implementation.

The primary purpose of Pop Lang's philosophy is to provide a language that feels immediately familiar to Luau programmers—utilizing local, function, and end blocks—while enforcing a strict type system and distinct semantic models for data structures like records, classes, and interfaces. This prevents "Lua regressions" where language features are secretly implemented through universal tables or metatables.

Sources: architecture/01-vision-and-principles.md:3-12, README.md:14-25, AGENTS.md:145-160

Core Language Identity

Pop Lang's identity is defined by three main pillars: Luau-shaped aesthetics, strong static typing, and native abstractions. The project explicitly rejects the "dynamic core" often found in scripting languages, choosing instead to ensure every operation has a statically proven type before execution.

Luau-Inspired Ergonomics

Pop Lang preserves the readable character of Luau, including:

• local and function keywords.
• Colon-method syntax (self).
• end blocks and low punctuation (no mandatory semicolons).
• Lightweight collection literals for arrays and tables.

Static Typing Invariants

Unlike Luau, Pop Lang has no source-visible any, Dynamic, or operational unknown types. Every expression must resolve to a concrete type. This is enforced through a semantic pipeline that moves from source to a typed/compile-time analysis before reaching intermediate representations.

Native Abstractions

Pop Lang separates concepts that are typically conflated in Lua. Records, classes, interfaces, modules, and namespaces are distinct semantic entities.

The following table summarizes the transformation of Lua concepts into Pop Lang native abstractions:

Lua/Luau Concept	Pop Lang Native Replacement
Universal Tables	Records, Classes, Interfaces, Typed Tables, or Arrays
Metatables/Metamethods	Native classes and typed operator protocols
require return values	File-scoped namespaces and analyzable initialization
IEEE-754 number	Explicit Int (Int64), Float (Float64), and fixed-width types
Implicit Globals	Explicitly rejected; all bindings must be local or namespace-scoped

Sources: architecture/01-vision-and-principles.md:14-50, README.md:30-45, architecture/09-relationship-to-luau.md:18-40, AGENTS.md:175-188

Architectural Principles

Pop Lang follows an "Architecture-to-Test-to-Implementation" workflow. The architecture documents are not merely suggestions; they are binding contracts. Any implementation that deviates from the accepted architecture is considered a bug.

Precedence of Authority

The project maintains a strict hierarchy for decision-making:

1. Latest Accepted ADR (Architecture Decision Record)
2. Integrated Architecture Documents
3. Language/Library/Runtime Specifications
4. Conformance Tests
5. Implementation

Forbidden Lua Regressions

A critical principle is the prevention of "Lua Regressions"—changes that slide back into dynamic or table-centered semantics. Forbidden behaviors include:

• Using tables as universal objects or namespaces.
• Implementing class fields through hash lookup.
• Resolving members from runtime strings.
• Adding untyped variadic or multiple results.

The following diagram illustrates the relationship between code units and visibility boundaries in the Pop Lang architecture:

The diagram shows the ownership hierarchy: Items exist within Modules, which are grouped into Bubbles (the primary unit of internal visibility), which are contained in versioned Packages within a Workspace.

Sources: architecture/19-architecture-conformance-and-regression-policy.md:3-30, AGENTS.md:105-125, AGENTS.md:275-295

API Design & Paradigm Style

Pop Lang is non-OOP by default. It prefers data and functions over deep class hierarchies. Classes are reserved for cases requiring stable identity or encapsulated mutable lifecycles.

Paradigm Priorities

1. Data First: Records and tagged unions for data representation.
2. Transformation Second: Plain functions in namespaces for operations.
3. Composition Third: Assembling capabilities rather than inheritance.
4. Nominal Interfaces: Small polymorphic boundaries.
5. Classes: Reserved for stable identity or required runtime dispatch.

Concise APIs and Cost Contracts

Public APIs must be optimized for "common call sites." A standard operation should typically require a single call. However, this convenience must not hide performance costs. Every public operation must document its "Cost Class," including:

• Allocation: Does it allocate memory?
• Copying: Does it perform defensive copies?
• Dispatch: Is it a direct call or virtual dispatch?
• Complexity: Asymptotic time/space complexity (e.g., O(n)).

Sources: architecture/01-vision-and-principles.md:52-66, architecture/decisions/0032-concise-apis-and-cost-contracts.md:10-25, AGENTS.md:200-215

Technical Pipeline & Backend Neutrality

The Pop Lang compiler architecture is designed to be backend-neutral. This ensures that language semantics remain identical whether the target is LLVM machine code, an interpreter, or a future VM.

The sequence diagram represents the data flow from source code to the final backend. HIR (High-level Intermediate Representation) preserves language concepts, while MIR (Middle-level Intermediate Representation) makes all runtime operations, such as garbage collection (GC) safe points, explicit.

MIR as the Semantic Contract

The MIR serves as the binding contract for all backends. It makes evaluation order, effects, failures, and GC behavior explicit. Backend-specific disagreement is considered a bug unless it stems from a documented target capability.

Sources: architecture/01-vision-and-principles.md:78-85, AGENTS.md:320-335, README.md:188-205

Summary of Principles

Pop Lang is defined by a commitment to static safety, architectural integrity, and Luau-like readability. By treating architecture as a binding contract and explicitly rejecting dynamic Lua patterns, the language provides a predictable foundation for native application development. Key significance lies in its "no-operational-dynamic-escape-hatch" rule, ensuring that the performance and safety of the system remain transparent to both the developer and the compiler.

Sources: architecture/01-vision-and-principles.md:120-135, AGENTS.md:380-400