GBR: ADR-0009 Operação "Código Cristalino" (Cartografia Semântica e Tratamento de Erros)

*Status:* Aceito *Data:* 2026-05-01

*Contexto:*

Durante a fase de prototipagem intensiva para estabelecer o framework P2P e o túnel reverso, a equipe atingiu os objetivos funcionais, mas acumulou dívida técnica. Havia uso frequente de avaliações inseguras (let assert), que em caso de falha causam o encerramento abrupto do processo (Crash) na Erlang VM. Além disso, a falta de padronização nas assinaturas arquiteturais dos Atores (alguns usando loop, outros handle_msg) e a escassez de documentação de contexto aumentavam drasticamente a curva de aprendizado (Onboarding) e o risco de manutenção para futuros engenheiros.

*Decisão:*

1. *Cartografia Semântica Obrigatória:* Imposição do uso de Docstrings nativos do Gleam (///) e comentários de linha (//) para documentar não apenas o "o que" a função faz, mas o "porquê" arquitetural, mapeando fluxos de dados complexos (ex: Piper <-> Yamux).
2. *Erradicação de Asserts:* Substituição sistemática de let assert por retornos monádicos do tipo Result(Ok, Error). A filosofia passa a ser a de Graceful Degradation (Degradação Graciosa): se uma validação falhar, o Nó Erlang não deve morrer; ele deve registrar o erro e manter os demais serviços operantes.
3. *Padronização do Template OTP:* Todo novo Ator no ecossistema deve seguir uma taxonomia estrita: definição de Type Message, definição de Type State, função start (ponto de entrada) e função loop (laço recursivo).

*Consequências:*

• *Positivas:* Transformação da base de código em um ativo de grau corporativo (Enterprise-grade); aumento brutal na previsibilidade do sistema em produção; blindagem contra quedas em cascata da Árvore de Supervisão.
• *Negativas/Riscos:* Aumento da verbosidade do código devido ao tratamento exaustivo de erros (case matchings extensos). Exigirá maior rigor nas revisões de código (Pull Requests) para garantir que o padrão seja mantido.