Public Standard-Library Architecture

Relevant source files

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

• architecture/22-public-standard-library-architecture.md
• architecture/decisions/0030-native-public-standard-library.md
• architecture/decisions/0031-public-library-tiers-and-names.md
• architecture/decisions/0032-concise-apis-and-cost-contracts.md
• architecture/22.6-standard-library-implementation-plan.md
• crates/libraries/README.md
• AGENTS.md

The Public Standard-Library Architecture in Pop Lang defines a native, statically typed foundation designed for portability, explicit performance contracts, and concise usability. It moves away from historically object-oriented "Base Class Library" (BCL) models, instead prioritizing functions, immutable records, and explicit resource management. The architecture is structured around two foundational Bubbles: Pop.Internal, which contains trusted compiler/runtime primitives, and Pop.Standard, which provides the public, portable API surface.

This architecture ensures that Pop Lang remains visually lightweight—retaining its Luau-inspired character—while enforcing strict static guarantees. It mandates that every operation has a predictable cost and that core capabilities like I/O, networking, and data formats are categorized into a clear distribution tier model. The library is designed to be backend-neutral, reaching native services through the versioned Pop Lang Runtime Interface (PLRI).

Sources: architecture/decisions/0030-native-public-standard-library.md:7-15, crates/libraries/README.md:9-16, AGENTS.md:520-530

Core Architectural Principles

The standard library is governed by several strict invariants that distinguish it from dynamic or purely object-oriented systems:

• Non-OOP Default: The library favors local values, functions, records, and tagged unions over complex class hierarchies. Classes are reserved for stable identity or mutable lifecycles.
• Static Safety: No operational dynamic fallback (like Any or Dynamic) is permitted. All operations must be compiler-proven.
• Explicit Cost Contracts: APIs must document their asymptotic complexity and behavior regarding allocation, copying, and dispatch.
• Backend Neutrality: The library remains portable across LLVM, interpreters, and future VMs by adhering to the PLRI semantic contract.

Sources: AGENTS.md:38-50, architecture/decisions/0032-concise-apis-and-cost-contracts.md:16-24, architecture/decisions/0030-native-public-standard-library.md:12-20

Library Layers and Dependency Direction

The toolchain provides two reserved foundational Bubbles with a strict one-way dependency flow.

Pop.Internal

A trusted boundary containing intrinsics, GC/ABI bridges, and platform adapters. It is never referenced directly by user code. It provides the low-level machinery required for the language to function on specific host platforms.

Pop.Standard

The portable public foundation. It depends on Pop.Internal, but the inverse is strictly forbidden. It provides the curated prelude and standard namespaces used in ordinary application development.

Usability and Naming Conventions

Pop Lang uses a "concise but complete" naming philosophy. Names represent stable capabilities rather than implementation roles (e.g., Json.decode instead of JsonDecoderFactory).

Naming Rules

• PascalCase: Used for namespaces, types, interfaces, and attributes.
• camelCase: Used for functions, methods, and Modules.
• Word Casing: Technical abbreviations are treated as words (e.g., Json, Http, Utf8, Ffi).
• Explicit Qualifiers: Namespaces like Unsafe, Native, and Experimental are used as final segments to mark boundaries of trust or stability.

Category	Example Root	Description
Data Formats	Json, Xml, Toml	Direct access to format codecs.
System	Process, Platform	Access to host environment and execution state.
Observability	Telemetry	Unified root for logs, traces, and metrics.
I/O	Io, File, Path	Filesystem and stream operations.

Sources: AGENTS.md:428-445, architecture/decisions/0031-public-library-tiers-and-names.md:11-25, architecture/decisions/0032-concise-apis-and-cost-contracts.md:30-45

Cost and Performance Model

A critical requirement for the public standard library is the transparency of "cost." Every API is evaluated based on its impact on the runtime.

• Views and Slices: These are non-owning and do not allocate; their lifetime is strictly bound to the owner.
• Iterators: Adapters are lazy and allocation-free by default.
• Explicit Allocation: Functions that materialise collections or grow buffers must document this behavior.
• Native Boundaries: Crossings between Pop code and native host code are explicit effects and are batched for efficiency.

Sources: architecture/decisions/0032-concise-apis-and-cost-contracts.md:51-64, architecture/22.6-standard-library-implementation-plan.md:15-30

Implementation and Distribution Tiers

The library is delivered in phases, categorized by domain and distribution tier. Official extensions like Pop.Data or Pop.Ai are independently versioned Packages that do not enter the fixed prelude.

Implementation Phases

Phase	Key Deliverables	Required Gates
Baselines	Pop.Standard prelude, status metadata	Rejection of dynamic/OOP patterns.
Core Values	Math, Sequence, Text, Unicode	Allocation/copy fixtures; complexity benchmarks.
I/O & Host	File, Directory, Process, Path	Fault injection, cleanup/cancellation tests.
Network	Http, Net, Socket, Crypto	Backpressure and isolation tests.

Sources: architecture/22.6-standard-library-implementation-plan.md:7-40, AGENTS.md:532-538

Technical Wiki Summary

The Public Standard-Library Architecture provides a structured, multi-tiered ecosystem for Pop Lang. By strictly separating portable foundations from native internal primitives and maintaining a rigorous cost model, it ensures that the language remains efficient enough for systems programming while preserving the readability of a scripting language. The reliance on Result-based error handling and explicit resource management eliminates the need for complex runtime exception machinery.

Sources: architecture/decisions/0030-native-public-standard-library.md:12-25, architecture/decisions/0032-concise-apis-and-cost-contracts.md:11-18