Development
Internal architecture, conventions, and material for contributors.
Architecture
- Aipo — Architecture Overview (Waves 1–2)The dependency direction is strictly unidirectional and acyclic: CLI → Runtime / VM → Bytecode → Core IR → Sema → HIR → AST → Syntax → Lexer → Source…
- ADR 001: Architectural baseline and Clean Architecture principles
- Bytecode & Virtual MachineAipo executes natively on a deterministic bytecode virtual machine, optimized for low memory footprint and high-throughput instruction dispatch.
- Architecture and Clean Code ContractThis document defines the mandatory software engineering contract for all implementations in this project.
- Compiler FrontendThe Aipo frontend ingests raw UTF-8 source text and produces a validated semantic representation.
- Workspace Crate ContractsThe Aipo codebase is structured as a collection of modular Rust crates, each enforcing strict domain boundaries and acyclic dependency graphs.
- Host ABI & SandboxingThe Host ABI (aipo-host) governs the sandboxing boundary and isolation model bridging Aipo scripts and host runtime environments (such as game…
- JavaScript Backend (aipo-js)The Aipo JavaScript backend transpiles Aipo source code directly to modern JavaScript (ES2022) with 100% behavioral parity guarantees.
Decisions
- ADP-001 — Core Types and Bytes as ValuesThe Aipo language required a clear strategy for handling raw binary byte streams, collection slicing, and bounded mathematical clamping operations.
- ADP-002 — Construction Hooks and Runtime ContractsThe language needed a unified, low-cognitive-overhead mechanism to validate struct states without requiring developers to write verbose boilerplate…
- ADP-003 — Execution BudgetsWhen running untrusted scripts in host environments (game engines, plugin sandboxes, or user-authored automations), preventing infinite loops from…
- ADP-004 — Unicode Identifier PolicyUnicode identifiers with different normalization forms (NFC vs NFD) can render identically on screen while representing completely distinct byte…
- ADP-005 — Parser Recursion LimitsRecursive-descent parsers can suffer from stack overflows when encountering deeply nested syntactic inputs (such as ((((...10,000…
- ADP-006 — Open Decisions for Waves 3 & 4Consolidation of open design decisions regarding asynchronous concurrency, task combinators, and Host ABI capability scoping.
- ADP-007 — Package Identity & DistributionThe language needed a modern dependency management system avoiding historical pitfalls found in package ecosystems like npm and PyPI: dependency…
- ADP-008 — Scoping Language Release v0.1.0Following the completion of Waves 0 through 5, it was essential to establish an uncompromising boundary for the initial public stable release…
- ADP-009 — Synchronous Versioned C ABITo enable embedding Aipo as a scripting engine in hosts written in C, C++, Zig, or other systems languages without requiring complex Rust bindings, a…
- ADP-010 — Thin Interoperability Proofs (Rust, C, JS)Ensure that v0.1.0's promise of cross-ecosystem interoperability is not merely theoretical, but validated by automated tests running across each…
- ADP-011 — Structural Performance & Ergonomics RoadmapDuring phase P04 and early P05, seven local micro-optimization experiments failed to produce reproducible speedups and were accordingly rolled back.
- ADP-012 — Canonical Syntax Ergonomics and Design Philosophy
- ADP-013 — WebAssembly Execution Substrate Migration and Self-Hosting RoadmapDuring the development of the v0.1.0 release of the Aipo programming language, deep bytecode interpreter optimizations were implemented and…
Proposals (ADP)
- ADP-001 — Byte, Bytes and types as values in Prelude V1The no-invention policy (prumo.json → risk, docs/language/authority-map.md) requires that every material semantic decision without an answer in the…
- ADP-002 — Construction hooks, invariants and runtime contractsThe no-invention policy (prumo.json → risk) requires that every gap between the canon and the implementation be recorded, not silenced. Slice S11…
- ADP-003 — Execution Budgets for Untrusted Programs (fuel, memory, interruption)This ADP closes when a design goal specifies the signal, scope, accounting and parity rule above, with fixtures proving each — or explicitly scopes…
- ADP-004 — Unicode Identifier and Security Policy
- ADP-005 — Parser Recursion Bounds (Nesting Limits)
- ADP-006 — Wave 3/4 Open Decisions (async, collections, packing, host)Canon shows Set as a type with .lazy() but defines no literal or call form, and V1 established that List/Dict/Bytes have no call form. Decision…
- ADP-007 — Package identity and distributionExample: acme.http. The coordinate is the canonical identity used in the manifest, lockfile, SourceMap and diagnostics. Segments use the ASCII…
- ADP-008 — Release aipo v0.1.0 and the interoperability boundaryAipo already has an executable foundation: language, VM, JavaScript backend, async, contracts, internal host ABI, local/GitHub packages and basic…
- ADP-009 — Synchronous, versioned C ABIaipo v0.1.0 exposes a synchronous, single-threaded, versioned C ABI. The ABI will be implemented in a separate crate, without exposing Rust structs…
- ADP-010 — Thin interoperability proofs for Rust, C and JavaScriptThe choice of library considers a clear API, compatible license, maintenance, ownership and testability. Popularity and size are not sufficient…
- ADP-011 — Structural performance and language ergonomics roadmapDuring phase P04 and the start of P05, seven local micro-optimization experiments (name pool, dense layout with 2 vectors, per-slot fixed-flag cache…
Governance
- Official Project ChangelogAll notable changes, releases, and milestones of the Aipo programming language are documented here, adhering to Keep a Changelog and Semantic…
- Prumo CLI & LPC MethodologyAipo utilizes Prumo v0.6 as its continuous governance framework alongside the Lean Progressive Context (LPC) methodology to orchestrate precision…
- Repository Governance
- Security & SandboxingAipo security architecture is anchored in the principle of least privilege and proactive runtime vulnerability mitigation.
- Code Standards & Testing StrategyAipo's engineering integrity is upheld by an exhaustive automated test pyramid and strict compilation standards in Rust 2024.
Evidence
- Language Conformance MatrixThe Aipo conformance suite guarantees that language semantics and specifications are maintained across all builds and targets.
- Cross-Language BenchmarksAipo provides a standardized benchmarking harness (aipo-bench --compare) evaluating wall-clock execution speed and memory footprint (Peak RSS)…
- Evidence — P00-G09 / Slice S9 (Runtime & Minimum Stdlib)Proof attachments for the required gates. Commands are reproducible from the repository root.
- Evidence — P00-G10 / Backend Completion (gaps inside S1–S9)Proof attachments for the required gates. Commands are reproducible from the repository root.
- Evidence — P00-G11 / Slice S10 (CLI + Formatter)Proof attachments for the required gates. Commands are reproducible from the repository root.
- Evidence — P00-G12 / Slice S11 (Conformance Hardening & MVP Gate)Proof attachments for the required gates. Commands are reproducible from the repository root. The corpus layout and snapshot matrix live in…
- Evidence — P00-G13 / MVP Construction Hooks & BytesProof attachments for the required gates. Commands are reproducible from the repository root.
- Evidence — P00-G14 / Runtime Contract EnforcementProof attachments for the required gates. Commands are reproducible from the repository root.
- Evidence — P00-G15 / Static Contracts and Interface ConformanceProof attachments for the required gates. Commands are reproducible from the repository root.
- Evidence — P00-G16 / Wave 1 Exit ReviewProof attachments for the required gates. Commands are reproducible from the repository root. The corpus specification lives in…
- Evidence — P01-G01 / JS Parity for the Full MVP SubsetProof attachments for the required gates. Commands are reproducible from the repository root. The Wave 2 plan lives in…
- Evidence — P01-G02 / Deep Quality Gauntlet23 examples (01–05 pre-existing, 06–24 new), each with committed .stdout, each verified on VM and Node by examples.rs. Detailed per-example table in…
- Evidence — P02-G01 / Wave 3 Tipos e Valores (Set, Sequence, Bytes Packing, Task, Duration)
- Evidence — P02-G02 / Wave 3 Stdlib: Combinadores Assíncronos e Operações de Task
- Evidence — P02-G03 / Wave 3 Infra: Sintaxe async fn, await do e Diagnósticos Estáticosprumo validate / prumo doctor cannot run in this environment: the local prumo 0.6.0 installation is missing its framework resources (framework-check…
- Evidence — P03-G01 / Host ABI: Capability Model, Host Values and Generational Handles
- Evidence — P03-G02 / Poppy Adapter and Deterministic Headless Demo
- The Optimization Saga & Methodological RigorA central engineering takeaway from the Aipo project is the discipline of empirical measurement: optimizations that look compelling in theory…
- Historical Slice RegisterEvery vertical slice and milestone in Aipo is completed only after automated evidence passes and a formal certification report is recorded in…
Performance
- Aipo Performance BaselineThese numbers are baselines for future comparison on a dedicated runner, not pass/fail thresholds. For the multi-runtime protocol, raw samples…
- Aipo Cross-Language BenchmarksCompare the cost of equivalent workloads without hiding the difference between interpreter, JIT, VM and native code. Rust native is an algorithmic…
Design
Zoe
- Getting Started with Zoe UIThis guide walks you through setup, initialization, and application lifecycle with Zoe UI.
- Advanced WidgetsSpecialized, high-complexity widgets tailored for developer tooling and IDE applications.
- Buttons & Selection ControlsInteractive components for triggering actions and toggling states.
- Creating Custom Components
- Input FieldsPrecision input components designed for developer tooling and numeric editing.
- Layout ContainersStructural containers for spatial arrangement with the Leona layout engine.
- The Leona 2.0 Layout Engine
- Navigation & Tree ListsComponents for tab switching and hierarchical data inspection.
- Interactive Zoe UI PlaygroundExplore Zoe UI and the Leona layout engine directly inside the documentation.
- Reactivity & Signals in Zoe UIZoe UI adopts a signal-based reactivity model, delivering clean ergonomics without virtual DOM overhead.