RFC 050 - Padrões de Codificação e Organização Definitiva do Workspace
Status: Ratificado (Standards Track) Pilar: Fundamentos / Engenharia
1. Padrões de Design e Codificação (O Rigor do Código)
Para que o ecossistema mantenha sua qualidade e modularidade escalando do microcontrolador ao mainframe, todo código submetido ao repositório deve obedecer a quatro dogmas inquebráveis:
- Isolamento Absoluto (Arquitetura Hexagonal): A regra de ouro é separar estritamente as regras de domínio da infraestrutura. O núcleo matemático não deve saber nada sobre redes ou discos. A inversão de dependência é mandatória através de Ports (Traits em Rust).
- Paradigma GALS e Atores (Sem Condições de Corrida): O estado interno nunca é compartilhado via bloqueios globais pesados. O protocolo adota o Actor-like State, onde cada componente (Kernel, Biologia, Economia, C.A.P.I.B.A.) comunica-se exclusivamente via troca de mensagens baseada em eventos.
- Pragmatismo de Hardware (
no_stdFirst): O núcleo do código de domínio deve ser compilável sem a biblioteca padrão (no_std), garantindo sua execução em microcontroladores voltados para energy harvesting. - Interoperabilidade Blindada (Opaque Handles): Para integrar de forma segura as 13 linguagens suportadas, o Foreign Function Interface (FFI) deve exportar apenas ponteiros opacos (Opaque Handles), prevenindo vazamentos de memória para as linguagens hospedeiras.
2. Organização Definitiva dos Módulos (A Planta Baixa do Repositório)
A estrutura de diretórios do repositório espelha exatamente os Bounded Contexts mapeados teoricamente. O diretório crates/ abriga as bibliotecas fundamentais do ecossistema e suas regras puras de domínio. A camada de aplicação, localizada em apps/ (ou diretórios adjacentes de interface), consome essas bibliotecas para gerar os binários e bindings finais.
| Diretório Físico | Contexto Delimitado | Responsabilidade Estrutural |
|---|---|---|
crates/paebiru-math | Fundamentos / Shared | Isola a stack matemática, contendo simulações termodinâmicas e a correção Reed-Solomon. |
crates/paebiru-kernel | Espinha Dorsal | Orquestra o Proof-of-Location e mecanismos de consenso baseados em Governança ZK. |
crates/paebiru-biology | Organismo | Implementa a Autopoiese Rizomática, Consciência de Grupo e roteamento estigmergico. |
crates/paebiru-economy | Tecido | Abriga o Barter Engine e a lógica de escambo de capacidades físicas e computacionais. |
crates/paebiru-capiba | Infraestrutura de Dados | Memória causal, blocos imutáveis e persistência termodinâmica (Nascente/Oceano). |
crates/plasmids | Máquina de Estado | Motor de parsing e execução da DSL em TOML que define os Plasmídeos (Intenções Soberanas). |
crates/hal | Adapters (Hardware) | Camada de abstração de hardware multiarquitetura focada em dispositivos ultrarrescritos. |
apps/cli | Interface / Usabilidade | Utilitário de terminal com comandos operacionais críticos como status, metabolism, view e flash. |
crates/sdk | Fronteira / Integração | Abstração de alto nível para desenvolvedores, contendo o Context, SovereignReceipt e a auto-negociação x402. |
crates/bindings/ | Interoperabilidade (FFI) | Fronteira que utiliza Opaque Handles para conectar o core em Rust às linguagens hospedeiras. |
3. Automação, Infraestrutura e Scripts (A Linha de Montagem)
Para garantir a qualidade, testabilidade e o ciclo de vida da aplicação de forma pragmática, os scripts de suporte são rigidamente estruturados e isolados da lógica de domínio:
- Provisionamento Determinístico (
infra/flake.nixeshell.nix): Scripts baseados em Nix para garantir que o ambiente de desenvolvimento seja reproduzível e idêntico para qualquer engenheiro da malha. - A Esteira Principal (
Makefile): Atua como o orquestrador primário de todos os comandos de build, geração de bindings, checagem de formatação e verificação formal. - Ambientes e Observabilidade (
Dockerfileedocker-compose.yml): Utilizados para conteinerizar instâncias de teste, rodar simulações de nós locais e levantar relatórios de observabilidade (ex:docker-compose.otel.yml). - A Muralha de Qualidade (
.github/workflows/): Define os gates rígidos de Integração Contínua (CI) para executar testes unitários, verificação formal e linting, blindando a branch principal contra qualquer tipo de regressão.
A prancheta de arquitetura está oficialmente trancada. As especificações normativas transformaram uma alucinação biomimética e cósmica em um ecossistema de software pragmático, modular e impiedosamente organizado.