GBR: ADR-0018 Sandboxing de I/O Cross-Platform e Equivalência com o NullClaw

• *Status:* Proposto
• *Data:* 2026-06-09

*Contexto:*

Ferramentas maduras de execução de agentes como o *NullClaw* utilizam mecanismos robustos de sandboxing no nível do Sistema Operacional (ex: Bubblewrap, Landlock no Linux ou containers Docker completos) para isolar operações de Entrada e Saída (I/O) das IAs. Embora seguros, estes isolamentos impõem sobrecargas consideráveis de latência, consumo de memória RAM extra e dependências pesadas de daemons do sistema, prejudicando a portabilidade em ambientes Windows 11 onde ferramentas como Landlock e Firejail não estão disponíveis de forma nativa.

Precisamos de uma solução para o gleambr_ai que proveja o mesmo nível de segurança para o sistema de arquivos do desenvolvedor, porém de forma 100% nativa na Erlang VM, cross-platform (Windows/Linux/macOS) e com custos operacionais próximos de zero.

*Decisão:*

Implementaremos o *Sandboxing de Chroot Lógico com Equivalência de Segurança* no nível do ecossistema BEAM/Gleam.

1. *Equivalência ao NullClaw:* Nossa solução atinge a mesma finalidade de bloqueio de Path Traversal que o sandboxing do NullClaw, confinando o agente estritamente em uma pasta de trabalho através do filepath.expand.
2. *Eficiência Inline:* Em vez de disparar processos externos pesados de contêineres ou namespaces do Linux, a normalização e validação de segurança ocorrem de forma assíncrona e inline dentro do processo do ator da ferramenta no Gleam, consumindo 0 bytes de memória adicionais no SO.
3. *Ponte com o SO Hospedeiro via FFI:* Utilizaremos chamadas de FFI nativas para os:type() da Erlang VM para realizar a normalização case-insensitive no Windows (protegendo contra desvios como C:\Proj vs c:\proj) e case-sensitive no Unix, eliminando falhas clássicas de contorno de diretório no Windows 11.
4. *Isolamento de Erros:* Exceções físicas de escrita/leitura são capturadas pelo wrapper FFI e retornadas como variantes estruturadas de erro do Gleam (ex: Error("Path Traversal detectado")), impedindo que falhas de segurança derrubem a thread do orquestrador ou vazem detalhes internos do SO.

*Consequências:*

• *Positivas:* - *Eficiência Extrema:* Latência de validação na escala de microssegundos (inline), sem overhead de virtualização ou processos zumbis. - *Portabilidade Cross-Platform Imediata:* Funciona de forma idêntica no PowerShell do Windows 11 e no Terminal do Linux. - Zero necessidade de ferramentas externas do sistema operacional para o confinamento lógico de arquivos.
• *Negativas:* - Não restringe o consumo de memória RAM ou loops infinitos de CPU que o Agente possa gerar em ferramentas de terminal de comando (esse isolamento computacional será delegado ao Wasmtime no futuro).