GBR: ADR-0001 Ambientes Isolados, Sandboxing e RAG Local

• *Status:* Aceito
• *Data:* 2026-05-13

*Contexto:*

A construção da CLI gleambr_ai introduz a capacidade de um Agente Autônomo (guiado por LLM via BYOC) interagir diretamente com o sistema de arquivos local do desenvolvedor. Conceder acesso irrestrito de leitura e escrita cria um raio de explosão (Blast Radius) inaceitável, expondo o sistema a ataques de Path Traversal ou modificações destrutivas acidentais em arquivos de configuração (ex: gleam.toml). Além disso, modelos de IA sofrem de "alucinações" sintáticas ao gerar código Gleam devido à escassez de dados de treinamento atualizados. A mitigação de diretórios através de strings (ex: starts_with) apresenta falhas conhecidas de segurança no Windows 11 devido à insensibilidade a maiúsculas/minúsculas, diferentemente de ambientes Unix/Linux. Por fim, a necessidade de aprovação humana (Human-in-the-Loop - HITL) para ações destrutivas não pode bloquear a thread assíncrona da Erlang VM.

*Decisão:*

Implementaremos uma arquitetura de Sandboxing Contextual para o servidor MCP da Frente ALPHA, regida pelos seguintes pilares:

1. *Gleam Environments:* A CLI operará confinada em perfis estritos (carregados de .gbr_envs/*.toml) que delimitam a raiz permitida e listam arquivos protegidos.
2. *Detecção Nativa de SO:* A ferramenta FileSystem MCP utilizará a biblioteca filepath aliada a chamadas FFI para os:type() nativo da Erlang VM. Isso garantirá a sanitização correta de caminhos absolutos, aplicando normalização case-insensitive no Windows e case-sensitive no Linux, bloqueando matematicamente fugas de diretório.
3. *HITL Assíncrono via Ring Buffer:* Tentativas de escrita em arquivos protegidos não travarão o processo OTP. A intenção será persistida no gbr_disk_log com status Pendente, liberando a thread do worker MCP. O loop do REPL no terminal lerá esse estado do disco para solicitar a aprovação humana.
4. *RAG Determinístico Local:* Para eliminar alucinações de sintaxe, o Agente será instruído a utilizar ferramentas de Grep Semântico apontadas exclusivamente para o diretório build/packages/ local. O LLM usará o código-fonte baixado pelo próprio compilador Gleam como base de conhecimento primária.

*Consequências:*

• *Positivas:* - Mitigação completa de ataques de Path Traversal independente do sistema operacional anfitrião. - Eliminação da necessidade de infraestrutura em nuvem (Vector DBs) para a base de conhecimento do Gleam, garantindo precisão absoluta (o código gerado baseia-se no código compilável local). - A Erlang VM mantém sua alta taxa de transferência e resiliência, pois o fluxo de aprovação humana torna-se uma saga persistida em disco e tolerante a falhas.
• *Negativas:* - Aumento da complexidade arquitetural do REPL, que deixa de ser um simples loop de prompt para se tornar uma máquina de estados que monitora o gbr_disk_log. - Necessidade de desenvolver e manter implementações FFI específicas para a camada de segurança do sistema de arquivos.

Depreciado (mantido p/ análise) GBR: ADR-0001 Ambientes Isolados e Ferramentas Seguras (MCP) para gleambr_ai

• *Status:* Proposto
• *Data:* 13 de Maio, 2026

*Contexto:*

A CLI gleambr_ai atuará como um engenheiro de software autônomo, utilizando Modelos de Linguagem (inicialmente BYOC via Gemini) para escrever, refatorar e analisar código Gleam. No entanto, LLMs estão sujeitos a alucinações (ex: inventar versões de pacotes inexistentes ou sobrescrever arquivos de configuração críticos). Conceder acesso irrestrito de escrita ao disco rígido cria um raio de explosão (Blast Radius) inaceitável para o monorepo.

*Decisão:*

1. *Arquitetura de "Gleam Environments":* A CLI adotará um sistema de perfis configuráveis (ex: .gbr_envs/auth_builder.toml). Cada ambiente definirá estritamente o System Prompt, o diretório de trabalho raiz (chroot lógico) e a lista de protected_files (ex: gleam.toml, manifest.toml).
2. *Sandboxing (Chroot Semântico):* A ferramenta MCP FileSystem enjaulará o Agente. Todas as requisições de leitura/escrita serão resolvidas de forma absoluta contra o diretório raiz permitido (ex: ./src/). Tentativas de Path Traversal (../) falharão silenciosamente no nível do Agente, mas gerarão alertas no terminal.
3. *Human-in-the-Loop (HITL):* A CLI implementará um mecanismo de suspensão de execução. Se o Agente decidir invocar write_file em um arquivo protegido (ou tentar rodar gleam add), a CLI pausará a interação P2P/MCP e renderizará um prompt interativo no terminal para o humano: [Aprovar] / [Negar] / [Editar].
4. *Auto-Correção com Toolchain Gleam:* O Agente terá ferramentas integradas como gleam_check. Se ele gerar um código, a CLI compila em background. Se quebrar, a CLI não avisa o humano; ela devolve o erro do compilador direto para o Agente tentar consertar o erro sozinho (até um limite de retentativas).

*Consequências:*

• *Positivas:* Permite que a IA escreva código rapidamente sem risco de destruir o repositório; mitiga problemas de defasagem de treino (ex: versões erradas no gleam.toml) através da edição humana intermediária; melhora a qualidade do código entregue via auto-correção.
• *Negativas:* Maior complexidade na construção do REPL (Loop de Leitura/Avaliação) do terminal, que precisará pausar threads assíncronas para aguardar o input humano.

Análise da negativa

Análise Crítica: Mitigando o REPL com gbr_disk_log

*O Problema:* Como o REPL do terminal vai pausar uma thread assíncrona para o Humano aprovar a edição de um arquivo protegido?

*A Solução:* Utilizar o gbr_disk_log (nosso ring buffer) para gerenciar essa complexidade e garantir segurança.

*A Engenharia (Por que funciona):* Em vez de travar o processo da Erlang VM em um loop infinito esperando você digitar "Sim" ou "Não" (o que causaria timeout no MCP), nós tratamos o HITL (Human-in-the-Loop) como uma *Máquina de Estados baseada em Eventos no Disco*:

1. O worker MCP recebe a ordem do Gemini para alterar o gleam.toml.
2. A barreira de segurança bloqueia e grava no gbr_disk_log: Evento(ID: 1, Ação: Write, Alvo: gleam.toml, Status: PendingApproval). O worker OTP dorme.
3. O Loop do Terminal (REPL) está sempre lendo o gbr_disk_log. Ele vê o pendente e exibe a tela bonita para você aprovar.
4. Você aprova. O REPL grava no log: Evento(ID: 1, Status: Approved).
5. O worker acorda, lê a aprovação, salva o arquivo e responde ao Gemini.

Se máquina piscar a luz e a CLI fechar (Crash), quando você abrir de novo, o estado está no disco. Nenhuma aprovação foi perdida.