Static copy

Copied from docs/en/decisions/adp-012.md in https://github.com/poppy-team/aipo-lang (MIT). Pinned to revision ce47c4e070404fc41722ccd8e2b7b808b99062a8, blob 9ace2f37bbc6bbabc4a8504868578fa3e7e6d6db. The source repository remains canonical; this copy is refreshed through a sync pull request, not live.

ADP-012 — Canonical Syntax Ergonomics and Design Philosophy

• Status: Approved
• Date: 2026-09-26
• Deciders: Raillen & Poppy Team
• Phase: Canonical Language Architecture

---

Context and Cognitive Design Principles

Aipo is engineered to minimize cognitive overhead and deliver a clean, inclusive, and deterministic developer experience, tailored to be especially welcoming for neurodivergent developers (ADHD and dyslexia):

1. Unambiguous Visual Tracking: Code blocks must possess symmetric visual boundaries, providing full native support for rainbow brackets and automatic code folding in modern IDEs.
2. Semantic Mutability Unification: A single keyword must govern mutability across all language scopes. Immutability is the strict default; mutability requires explicit declaration with var.
3. Motor Symmetry in Data Structures: Key-value association must use the identical : syntax in dictionary literals and typed struct instantiations, eliminating motor dissonance and typo risks.
4. Ceremony-Free Structural Subtyping: Interface conformance must be purely structural and automatically verified by the compiler, enabling genuine library decoupling without declarative boilerplate.
5. Arithmetic Symmetry: Mathematical operators must be symbolic, intuitive, and symmetric with the broader computing ecosystem.

---

Canonical Architectural Decisions

1. Curly-Brace Block Delimitation ({ ... })

• All language blocks (fn, struct, impl, if, while, loop, repeat, each, match, attempt, await do) are enclosed in curly braces { ... }.
• Control flow conditions do not require and do not use parentheses: if x > 10 { ... }, while active { ... }, each item in list { ... }.
• This ensures immediate visual balance, native rainbow bracket alignment, and fluent structured navigation in code editors.

2. Immutability by Default in Structs

• In struct declarations, all fields are strictly immutable by default. Simply declare the field identifier (id, created_at).
• When a field requires mutability across the instance lifecycle, it must be explicitly prefixed with var: var status = "offline".
• Reassigning fields not declared with var is statically rejected by the compiler (AIPO_SEM_IMMUTABLE_FIELD_REASSIGN).

3. Key-Value Symmetry in Instantiations (:)

• Struct instantiation follows the canonical StructName{ field: value, ... } syntax, matching dictionary literals { "key": value } with complete motor symmetry.

4. Universal Mutability via var self

• In impl blocks, unannotated receivers are strictly read-only (self).
• When a method mutates instance fields, it explicitly declares var self: fn increment(var self) { ... }.
• This unifies the entire language around a single rule: var is the universal keyword for mutability.

5. Automatic Structural Subtyping for Interfaces

• Interface type conformance is structural and automatic. If a struct implements all required methods with compatible signatures (arity, parameters, return types, and receiver mutability), it satisfies the interface transparently.
• No bureaucratic implementation keywords or orphan declarations are required.

6. Symbolic Integer Division Operator (// and //=)

• Truncated integer division towards zero and its compound assignment form are expressed via canonical // and //=, preserving symbolic harmony alongside +, -, *, /.

7. Complete Suite of Expressive Loops

• The language provides four orthogonal loops to cover every programmatic pattern without contortions: loop { ... } (unconditional), while c { ... } (conditional), repeat n { ... } (finite count), and each x in col { ... } (collection iteration).

---

Summary of Syntax Guidelines & Cognitive Benefits

Canonical Guideline	Canonical Syntax	Cognitive & Ergonomic Benefit
Structured Blocks	if c { ... }, fn f() { ... }	Unambiguous visual scope with native rainbow brackets and code folding
Struct Immutability	struct User { id, var status }	Immutability by default; mutation requires explicit intent via var
Symmetric Instantiation	User{ id: "1", name: "Ana" }	Perfect visual and motor symmetry with dictionary literals { k: v }
Mutator Receiver	fn inc(var self) { ... }	Semantic unification: var is the universal keyword for mutability
Formal Interfaces	interface Drawable { ... }	Pure structural subtyping without boilerplate ceremony or artificial coupling
Integer Division	a // b, a //= b	Mathematical consistency and symmetry with all arithmetic operators

---

Compiler Architecture Impact

1. aipo-lexer: Emits SlashSlash (//), SlashSlashEq (//=), curly braces { and }, and canonical keywords.
2. aipo-syntax: Parses recursive brace blocks, immutable fields by default, explicit var, and struct instantiation with :.
3. aipo-sema: Enforces static type checking, field immutability, structural interface conformance, and var self receiver validation.
4. aipo-formatter: Ensures idempotent formatting with 4-space indentation and canonical brace alignment.
5. aipo-vm, aipo-wasm, & aipo-js: Emit and execute corresponding code with 100% bit-exact determinism across backends.