prometeu-runtime/docs/runtime/agendas/006-break-monolith-runtime.md

Agenda - Break Monolith Runtime

Problema

Partes críticas do runtime cresceram como monólitos:

• dispatcher de syscalls concentrado em um arquivo enorme;
• lógica de VM e testes unitários convivendo no mesmo arquivo gigante;
• fronteiras entre domínio, orquestração e teste cada vez menos nítidas.

Isso hoje é visível principalmente em:

• prometeu-vm/src/virtual_machine.rs
• prometeu-system/src/virtual_machine_runtime.rs
• prometeu-hal/src/syscalls.rs

Dor

• Evolução fica cara porque qualquer mudança exige navegar arquivos enormes.
• Review perde precisão: comportamento, helper, contrato e teste se misturam no mesmo lugar.
• A chance de regressão cresce porque a coesão está baixa e o isolamento entre domínios está fraco.
• O custo cognitivo para novos contribuidores já está alto demais para o estágio do projeto.
• Testes internos gigantes mascaram ownership ruim de comportamento.

Alvo da Discussao

Definir uma estratégia de modularização do runtime que preserve as invariantes atuais, mas reduza o acoplamento estrutural.

O objetivo não é "fatiar por estética". É:

• extrair dispatcher de syscalls por domínio;
• separar responsabilidades dentro do runtime;
• tirar testes unitários do arquivo monolítico da VM quando fizer sentido;
• manter discoverability e rigor arquitetural.

O Que Precisa Ser Definido

1. Topologia de módulos. Como dividir syscalls por domínio:

   • system
   • gfx
   • input
   • audio
   • fs
   • log
   • asset
   • bank

2. Dono da orquestração. O que continua no runtime central e o que migra para módulos/serviços especializados.

3. Estratégia para a VM. Quais blocos de virtual_machine.rs devem virar módulos dedicados:

   • execução/opcodes
   • loader init
   • syscalls
   • GC/safepoint hooks
   • helpers de testes

4. Estratégia de testes. Quais testes permanecem próximos ao módulo e quais viram integração.

5. Critério de coesão. Como evitar trocar um monólito por vinte arquivos arbitrários sem fronteira real.

O Que Necessita Para Resolver

• mapa atual de responsabilidades por arquivo;
• proposta de topologia modular;
• critério de migração de testes;
• definição clara do que é API interna entre módulos;
• plano incremental de refactor sem quebrar o runtime no meio.

Fora de Escopo

• redesign funcional do comportamento da VM;
• reescrita completa do runtime;
• reorganização cosmética sem ganho de ownership.

Critério de Saida Desta Agenda

Pode virar PR quando houver:

• proposta de módulos aprovada;
• fronteira clara entre dispatcher, domínio e orquestração;
• plano para testes unitários e integração;
• estratégia incremental que preserve o comportamento existente.