GBR: ADR-0010 Extração do Motor Universal de Roteamento Dinâmico (gbr_dispatcher)

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

*Contexto:*

Originalmente, a lógica de criação de Atores sob demanda (Cold-Start) e o roteamento baseado em ETS residiam dentro do projeto gbr_monitor. No entanto, o nosso ecossistema é estritamente *Stateful por Alvo (Target)*. A telemetria de uma máquina específica e o estado da sua rede BPMN/Yamux precisam estar acoplados ao mesmo Ator em memória. Como outras ferramentas do ecossistema precisarão deste mesmo comportamento, o acoplamento no gbr_monitor tornou-se um anti-padrão. Além disso, a ocorrência de picos de ingestão (Thundering Herd) gerava Condições de Corrida (Race Conditions), onde múltiplos processos da API Web tentavam instanciar o mesmo Ator simultaneamente.

*Decisão:*

1. *Desacoplamento Universal:* Extração de toda a lógica de roteamento em memória, cache ETS e instanciação de Atores para a biblioteca agnóstica shared/gbr_dispatcher.
2. *Resolução de Concorrência via Trava Atômica (Atomic Lock):* Para resolver a condição de corrida de instanciação sem utilizar Mutexes bloqueantes, adotou-se o uso estrito de gbr_ets.insert_new/3. Sendo uma operação atômica em C na máquina virtual, apenas a thread que conseguir inserir o registro ganha o "direito" de fazer o spawn do Ator. As threads perdedoras da corrida entram em um loop de repetição passiva (Micro-Retry) aguardando o Ator ser criado pelo vencedor e disponibilizado no ETS.
3. *Conversão de Tipos Segura (FFI Identity):* Consolidada a decisão (ADR-003) de utilizar uma função FFI privada (to_dynamic) para fazer o cast opaco do Subject Gleam para Dynamic na gravação do ETS, uma vez que o gbr_dispatcher é o único gerente desta tabela e pode garantir a sanidade da memória matematicamente.

*Consequências:*

• *Positivas:* O gbr_monitor agora é uma biblioteca puramente focada no domínio da Telemetria; o gbr_dispatcher pode ser publicado como um pacote independente (Hex Publish) para toda a comunidade Erlang/Gleam como um gerenciador de Atores Stateful imune a Race Conditions.
• *Negativas/Riscos:* A delegação da criação de Atores requer injeção de dependência de funções construtoras complexas (Factories) de domínio superior para dentro do dispatcher genérico.