# 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.