GBR: ADR-0017 Interfaces Seguras baseadas em Capacidades (Ocap) via Registros de Funções (Vtables)

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

*Contexto:*

No ecossistema de agentes autônomos, o acoplamento forte entre o cérebro do agente (LLM) e a execução física de ferramentas e integrações de canais gera código frágil e difícil de testar. Inspirados pelo benchmark de mercado *NullClaw* (escrito em Zig), que utiliza tabelas virtuais de funções (Vtables) para abstrair de forma limpa mais de 50 provedores de modelos, 19 canais de mensageria e dezenas de ferramentas locais, precisamos de um design que replique esse nível de desacoplamento, flexibilidade e segurança no Gleam.

Gleam é uma linguagem funcional estaticamente tipada que roda na Erlang VM. Ela não possui herança nem tabelas virtuais clássicas de C++ ou Zig, mas possui registros de tipos customizados (Custom Types) contendo campos que armazenam funções anonimizadas.

*Decisão:*

Adotaremos o padrão *Vtable em Gleam* usando registros de tipos com campos funcionais para representar interfaces de recursos e restrições de capacidades (Ocap).

1. *Abstração de Interfaces:* Provedores de LLM e Executores de Ferramentas serão expostos através de tipos públicos contendo fechamentos (closures). gleam pub type LlmProvider { LlmProvider( name: String, stream_inference: fn(List(Message), fn(String) -> Nil) -> Result(Nil, String), ) }
2. *Confinamento de Capacidades (Object-Capability - Ocap):* Uma ferramenta não receberá acesso irrestrito ao sistema; em vez disso, ela receberá uma estrutura contendo referências exclusivas às capacidades que pode executar (ex: gravar apenas em caminhos higienizados).
3. *Substituição Dinâmica:* Em tempo de execução, o orquestrador poderá alternar a implementação de um driver (ex: de OpenAI para Ollama local) apenas passando uma estrutura correspondente, permitindo mocks 100% testáveis nos testes unitários e de integração sem a necessidade de criar atores complexos de stubs.

*Consequências:*

• *Positivas:* - Desacoplamento arquitetural absoluto entre os provedores de modelos e o loop do orquestrador. - Testabilidade trivial: podemos mockar qualquer chamada externa passando funções puras inline. - Segurança aprimorada, pois os componentes só conseguem invocar o que está explicitamente contido em seu escopo de registro de capacidade.
• *Negativas:* - Ligeiro overhead sintático em Gleam para construir e passar os registros contendo funções.