🛡️ Qualidade — 4 Dogmas + 4 Esteiras

A Muralha da Qualidade do PAEBIRU tem 4 dogmas (o que é inegociável) e 4 esteiras (como o gate é executado em CI). Nenhuma regressão chega a main sem passar por todas as 4.

flowchart TB
    A[PR aberto] --> E1[Esteira 1<br/>Conformidade]
    E1 -->|passa| E2[Esteira 2<br/>GALS & Domínio]
    E2 -->|passa| E3[Esteira 3<br/>Verificação Formal]
    E3 -->|passa| E4[Esteira 4<br/>Embarcada]
    E4 -->|passa| M[main]
    E1 -->|falha| X[bloqueado]
    E2 -->|falha| X
    E3 -->|falha| X
    E4 -->|falha| X

Os 4 Dogmas Inquebráveis

Originais do AGENTS.md §4, ratificados como princípio de revisão. Um PR que viola qualquer dogma é rejeitado mesmo que funcione.

🛡️ Dogma 1 — Isolamento Absoluto (Hexagonal)

“A lógica de domínio é o núcleo sagrado. Infraestrutura é detalhe injetado via traits.”

Invariantes:

• crates/<bc>/src/domain/ não importa de actor/, ports/ ou adapters/. Verificado por:

  grep -rE '^use crate::(actor|ports|adapters)' crates/<bc>/src/domain/
  # deve retornar vazio
  

• Toda dependência de I/O passa por trait declarado em crates/<bc>/src/ports/.
• Cruzamento entre BCs é via artefato imutável com receipt — nunca Arc<Mutex<T>> compartilhado.

Sinais de violação:

• use std::net, use std::fs, use std::time::Instant em domain/.
• tokio::spawn ou mpsc::channel em domain/.
• Estruturas do BC A importadas diretamente em BC B.

🌀 Dogma 2 — Paradigma GALS & Ator

“Localmente síncrono, globalmente assíncrono. Nunca bloqueie dentro do loop do ator.”

Invariantes:

• Loops de ator usam apenas mpsc::Receiver::recv().await, tokio::select! ou similar. Nenhuma espera bloqueante.
• Estado mutável do ator é dentro do struct do ator; nada de Mutex<DomainState>.
• Mensagens entre BCs são serializáveis (Serialize + Deserialize).

Sinais de violação:

• std::sync::Mutex, std::sync::RwLock no domínio ou no ator.
• thread::sleep, std::thread::join em código de runtime.
• Operações de I/O síncronas (std::fs::read, std::net::TcpStream) sem wrapper async.

⚙️ Dogma 3 — no_std First

“O código de domínio deve compilar sem a biblioteca padrão, do ATmega ao mainframe.”

Invariantes:

• crates/kernel/src/domain/ compila para riscv32imc-unknown-none-elf e thumbv7em-none-eabihf sem warnings.
• crates/math/ compila para os mesmos alvos.
• Coleções dinâmicas usam heapless em vez de Vec/HashMap no caminho embarcado.

Sinais de violação:

• use std::collections::* em código domain/.
• Alocação dinâmica (Box, Vec, String) em código no_std.
• Dependências que exigem std automaticamente.

🔌 Dogma 4 — Interoperabilidade Blindada (Opaque Handles & Zero-Copy)

“O FFI expõe apenas ponteiros opacos. Serialização pesada é substituída por vistas diretas da memória.”

Invariantes:

• Tipos públicos do crate expostos a FFI usam #[repr(C)] + ponteiro opaco (sem campos públicos).
• Buffers compartilhados via FFI são zero-copy (ponteiro + tamanho).
• serde_json/protobuf proibidos em crates/bindings/* para caminhos quentes.

Sinais de violação:

• Tipos Rust complexos visíveis no header C.
• serde_json::from_str em hot path de binding.
• Vec<T> retornado através de fronteira FFI (vira cópia).

As 4 Esteiras da Muralha

Cada esteira tem um critério de saída binário (passa/falha). CI enforça em ordem. Uma esteira só é avaliada se a anterior passou.

Esteira 1 — Conformidade (sintática, estática, segurança básica)

Ferramentas:

Saída da esteira: zero erros, zero warnings de clippy, zero CVEs HIGH/CRITICAL.

Esteira 2 — GALS & Domínio (testes + cobertura)

Ferramentas:

Saída da esteira: suíte verde, cobertura ≥ 90 %, sem teste flaky.

Esteira 3 — Verificação Formal (TLA+ + Lean 4)

Verificação cirúrgica: aplicada só onde a garantia supera o custo de modelagem. Detalhes em formal-verification.md.

Ferramentas:

Saída da esteira: modelos compilam, provas não regrediram, contradições detectadas resolvidas.

Esteira 4 — Embarcada (no_std)

Ferramentas:

Saída da esteira: build limpo para todos os alvos embarcados suportados pela mudança.

Tabela de mapeamento: dogma × esteira

Como aplicar este documento

• Autor do PR: percorra a tabela para o dogma que sua mudança toca. Cada dogma tem testes específicos em cada esteira.
• Reviewer: use a tabela como checklist de revisão.
• Agente de IA: leia a skill paebiru-architect antes de propor patches que tocam dogmas. Cite o dogma preservado no PR.

Veja também

• AGENTS.md §4 — Convenções de código
• Processo RSE
• Verificação formal
• CONTRIBUTING.md §2 — Princípios inegociáveis
• Dicionário · Maturidade Causal