GBR: ADR-0002 Framework P2P Universal com Roteamento Dinâmico (Multistream-Select sobre ETS)

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

*Contexto:*

A versão inicial da malha gbr_p2p possuía os protocolos (Kademlia, GossipSub) acoplados diretamente ao código fonte (hardcoded). Quando o projeto evoluiu para o Falcon 2.0, exigiu-se a capacidade de registrar novos protocolos em tempo real (como o /horus/telemetry/1.0.0 para métricas e comandos reversos) sem precisar alterar a base do framework P2P, suportando uma abordagem agnóstica de Inversão de Controle. O desafio arquitetural era permitir essa inspeção profunda de pacotes (Deep Packet Inspection) e roteamento para o Ator correto sem criar contenção (bottleneck) em um processo OTP central durante o estabelecimento de milhares de conexões Yamux.

*Decisão:*

1. *Roteamento Dinâmico via ETS:* A API pública do Host agora expõe gbr_p2p.register_protocol(host, protocol_id, actor_spec). Esta função persiste a intenção em uma tabela Erlang Term Storage (gbr_p2p_protocols) otimizada com ReadConcurrency(True).
2. *Negociador Multistream-Select:* Quando um novo stream é aberto no multiplexador Yamux, o primeiro pacote lido não é tratado pelo domínio. O módulo yamux_stream atua como roteador/lexador; ele consome os bytes do cabeçalho do protocolo, realiza um lookup O(1) não-bloqueante na tabela ETS, instancia o Ator do domínio específico (ex: Telemetria ou Túnel) e faz o hand-off (repassa o controle do Stream) para o respectivo Ator.
3. *Padrão Builder e Isolamento de Configuração:* A configuração do Node (Timeouts, K-Buckets, Bootstrap Nodes) foi movida para uma ADT P2PConfig instanciada pelo Padrão Builder, garantindo imutabilidade e simplificando a Developer Experience (DX).

*Consequências:*

• *Positivas:* Transformação de um código monolítico em um verdadeiro Framework Universal. Permite que múltiplos Hosts P2P operem na mesma máquina virtual com configurações distintas (Cloud Edge vs IoT); roteamento de novos protocolos não afeta a latência da malha.
• *Negativas/Riscos:* A extração do handler do ator torna a depuração de falhas de conexão ligeiramente mais opaca, uma vez que pacotes cujo cabeçalho não correspondam a nenhum registro na ETS sofrerão drop silencioso (ou rejeição de protocolo no Multistream-select) sem envolver lógicas de negócio.