Cópia estática

Copiado de docs/decisions/adp-012.md em https://github.com/poppy-team/aipo-lang (MIT). Fixado na revisão ce47c4e070404fc41722ccd8e2b7b808b99062a8, blob 2dc37c8330635a96b2c00a858ae2d46c0e761e1f. O repositório de origem permanece canônico; esta cópia é atualizada por um pull request de sincronização, não em tempo real.

ADP-012 — Especificação de Ergonomia Sintática e Filosofia de Design Canônico

• Status: Aprovado
• Data: 2026-09-26
• Decisores: Raillen & Poppy Team
• Fase: Arquitetura Canônica da Linguagem

---

Contexto e Princípios de Design Cognitivo

O Aipo é projetado para minimizar a sobrecarga cognitiva e oferecer uma experiência de desenvolvimento límpida, inclusiva e determinística, especialmente convidativa para desenvolvedores neurodivergentes (com TDAH e dislexia):

1. Rastreamento Visual Inequívoco: Blocos de código devem ter correspondência visual simétrica e suporte pleno a extensões de destaque de pares (rainbow brackets) e dobragem de código (code folding) nativa em IDEs.
2. Unificação Semântica de Mutabilidade: Uma única palavra-chave deve governar a mutabilidade em todos os escopos da linguagem. Imutabilidade deve ser o padrão estrito; mutabilidade requer declaração explícita com var.
3. Simetria Motora em Estruturas de Dados: O mapeamento chave-valor deve usar a mesma notação (:) em literais de dicionários e na instanciação de estruturas tipadas, eliminando atrito motor e erros de digitação.
4. Subtipagem Estrutural Sem Cerimônia: A conformidade com interfaces deve ser puramente estrutural e verificada automaticamente pelo compilador, permitindo desacoplamento real de bibliotecas sem boilerplate declarativo.
5. Simetria Aritmética: Operadores matemáticos devem ser simbólicos, intuitivos e simétricos com o ecossistema moderno.

---

Decisões Arquiteturais Canônicas

1. Delimitação por Chaves ({ ... })

• Todos os blocos da linguagem (fn, struct, impl, if, while, loop, repeat, each, match, attempt, await do) são delimitados por chaves { ... }.
• Condições de controle de fluxo não exigem e não utilizam parênteses: if x > 10 { ... }, while ativo { ... }, each item in lista { ... }.
• Isso garante suporte imediato a rainbow brackets, balanceamento visual inequívoco e navegação estruturada fluida em editores de código.

2. Imutabilidade por Padrão em Estruturas

• Em struct, todos os campos são estritamente imutáveis por padrão. Basta declarar o identificador do campo (id, criado_em).
• Quando um campo necessita de mutabilidade durante o ciclo de vida da instância, ele deve ser prefixado explicitamente com a palavra-chave var: var status = "offline".
• A reatribuição de campos não declarados com var é rejeitada estaticamente pelo compilador (AIPO_SEM_IMMUTABLE_FIELD_REASSIGN).

3. Simetria de Chave-Valor em Instanciações (:)

• A instanciação de estruturas adota a sintaxe canônica StructName{ campo: valor, ... }, em total simetria com literais de dicionário { "chave": valor }.

4. Mutabilidade Universal com var self

• Em blocos impl, o receptor self sem anotação é estritamente somente-leitura (self).
• Quando um método realiza mutações nos campos da instância, ele declara explicitamente var self: fn incrementar(var self) { ... }.
• Essa regra unifica a linguagem: var é a palavra universal e suficiente para indicar mutabilidade.

5. Subtipagem Estrutural Automática para Interfaces

• A conformidade de tipos com interface é estrutural e automática. Se uma estrutura implementa os métodos exigidos com assinaturas compatíveis (aridade, parâmetros, retornos e compatibilidade de self/var self), ela satisfaz a interface de forma transparente.
• Não são necessárias palavras-chave burocráticas de implementação nem declarações órfãs no topo do arquivo.

6. Operador Simbólico de Divisão Inteira (// e //=)

• A divisão inteira truncada em direção a zero e sua forma composta são expressas pelos operadores canônicos // e //=, preservando harmonia simbólica com +, -, *, /.

7. Conjunto Completo de Laços Expressivos

• A linguagem disponibiliza quatro laços ortogonais para cobrir todas as necessidades sem artifícios: loop { ... } (infinito), while c { ... } (condicional), repeat n { ... } (contagem finita) e each x in col { ... } (iteração sobre coleções).

---

Resumo das Diretrizes Sintáticas e Benefícios Cognitivos

Diretriz Canônica	Sintaxe Canônica	Benefício Cognitivo & Ergonômico
Blocos Estruturados	if c { ... }, fn f() { ... }	Delimitação inequívoca com suporte nativo a rainbow brackets e folding
Imutabilidade em Structs	struct User { id, var status }	Imutabilidade por padrão; mutabilidade requer intenção explícita com var
Instanciação Simétrica	User{ id: "1", name: "Ana" }	Simetria motora e visual perfeita com literais de dicionário { k: v }
Receptor Mutador	fn inc(var self) { ... }	Unificação semântica: var é a palavra universal de mutabilidade
Interfaces Formais	interface Drawable { ... }	Subtipagem puramente estrutural sem cerimônias ou acoplamento artificial
Divisão Inteira	a // b, a //= b	Consistência matemática e simetria com outros operadores aritméticos

---

Impacto na Arquitetura do Compilador

1. aipo-lexer: Fornece os tokens SlashSlash (//), SlashSlashEq (//=), chaves { e } e palavras-chave canônicas.
2. aipo-syntax: Faz o parse recursivo de blocos com chaves, campos imutáveis por padrão, var explícito, e instanciação de structs com :.
3. aipo-sema: Realiza checagem estática de tipos, verificação de imutabilidade de campos, conformidade estrutural com interfaces e validação de var self.
4. aipo-formatter: Garante formatação idempotente com indentação de 4 espaços e alinhamento canônico de chaves.
5. aipo-vm & aipo-wasm & aipo-js: Emitem e executam código correspondente de forma 100% idêntica e determinística.