prometeu-runtime/docs/runtime/pull-requests/PR-019-[RUNTIME]-break-monolith-runtime.md

PR-019 [RUNTIME]: Break Monolith Runtime

Briefing

O runtime acumulou alguns monolitos que ja estao acima do limite aceitavel de ownership e review: prometeu-vm/src/virtual_machine.rs passou de 5k linhas, prometeu-system/src/virtual_machine_runtime.rs concentra orquestracao e dispatch em um unico arquivo, e prometeu-hal/src/syscalls.rs mistura catalogo, metadata, resolucao e testes em uma superficie unica.

Esta PR nao existe para "quebrar arquivo grande". Ela existe para restaurar fronteiras arquiteturais sem alterar as invariantes normativas do runtime. A referencia canonica continua sendo docs/runtime/virtual-machine/ARCHITECTURE.md; a modularizacao proposta abaixo precisa servir essa arquitetura, nao competir com ela.

Problema

• ownership estrutural esta difuso entre VM, runtime de sistema e superficie de syscalls;
• review perde precisao porque codigo de dominio, cola de orquestracao, helpers e testes convivem no mesmo bloco;
• testes internos gigantes escondem fronteiras ruins em vez de reforcar contratos pequenos;
• qualquer mudanca em GC, loader, scheduler ou syscall dispatch exige navegar arquivos que concentram responsabilidades demais;
• o risco atual e trocar evolucao arquitetural por manutencao oportunista em zonas de baixa coesao.

Alvo

• crates/console/prometeu-vm/src/virtual_machine.rs
• crates/console/prometeu-system/src/virtual_machine_runtime.rs
• crates/console/prometeu-hal/src/syscalls.rs
• testes diretamente acoplados a esses monolitos

Escopo

• Definir a topologia modular alvo para a VM, para o runtime de sistema e para a superficie de syscalls.
• Manter VirtualMachine, VirtualMachineRuntime e a API publica de syscalls como facades estaveis, movendo implementacao para modulos internos coesos.
• Separar tres tipos de responsabilidade que hoje aparecem colapsados:
  • catalogo e metadata;
  • execucao/orquestracao;
  • testes e fixtures.
• Mover testes unitarios para junto do modulo dono do comportamento quando isso reforcar ownership.
• Promover para testes de integracao apenas os cenarios que cruzam VM, runtime e hardware bridge.

Topologia Proposta

1. prometeu-hal/src/syscalls/

Objetivo: isolar definicao de contrato de syscall da logica de resolucao e da organizacao por dominio.

Estrutura alvo:

• mod.rs: facade publica atual (Syscall, SyscallMeta, resolve_*, meta_for)
• registry.rs: enum Syscall, SyscallIdentity, SyscallMeta, tabela canonica e helpers de lookup
• caps.rs: flags de capability e mapeamento capability -> syscall
• resolver.rs: resolve_syscall, resolve_program_syscalls, validacoes de ABI e capability
• domains/system.rs
• domains/gfx.rs
• domains/input.rs
• domains/audio.rs
• domains/fs.rs
• domains/log.rs
• domains/asset.rs
• domains/bank.rs
• tests/ ou modulos de teste adjacentes para resolver, metadata e cobertura de catalogo

Regra: dominio organiza catalogo e metadata; resolver nao vira dono de comportamento de runtime.

2. prometeu-system/src/runtime/

Objetivo: fazer VirtualMachineRuntime voltar a ser uma fachada de orquestracao, nao um deposito de regras de dominio.

Estrutura alvo:

• mod.rs: define VirtualMachineRuntime e reexporta a API publica existente
• state.rs: estado mutavel do runtime, handles, crash report, identity, ciclo de vida de cartridge
• lifecycle.rs: new, reset, initialize_vm, limpeza de estado e aplicacao de capabilities
• tick.rs: tick, debug_step_instruction, traducao de faults/panics e logica de frame logico
• dispatch.rs: roteamento de syscall por dominio, sem carregar regra de negocio inline
• domains/log.rs
• domains/fs.rs
• domains/input.rs
• domains/gfx.rs
• domains/audio.rs
• domains/asset.rs
• domains/bank.rs
• support.rs apenas se restar infraestrutura compartilhada claramente reutilizada

Regra: o runtime central coordena estado, VM e bridges; cada modulo de dominio implementa apenas o contrato daquele dominio.

3. prometeu-vm/src/virtual_machine/

Objetivo: separar interpretacao, loader, GC e ABI interna sem fragmentar a API publica da VM.

Estrutura alvo:

• mod.rs: define VirtualMachine e centraliza a fachada publica
• loader.rs: parse/load, patching de hostcalls, init e pre-condicoes de verificacao
• exec.rs: loop de execucao, step/run, dispatch de opcode e motivos de parada
• stack.rs: operand stack helpers, traps de underflow/type mismatch e operacoes primitivas
• calls.rs: prepare_call, call frames, locals e calling convention
• gc.rs: safepoint, coleta, root walking e invariantes de heap runtime
• syscall_abi.rs: ponte VM <-> NativeInterface, aridade, return slots e checagens defensivas
• breakpoints.rs se a logica de debugger continuar crescendo
• test_support.rs: fixtures internas pequenas que realmente pertencem a VM

Regra: nenhum modulo novo deve misturar loader, execucao e GC na mesma unidade "por conveniencia".

Criterio de Coesao

• cada modulo precisa responder por um unico eixo de invariantes que faca sentido em review;
• modulos podem compartilhar tipos, mas nao ownership difuso;
• mod.rs e facade, nao novo monolito;
• common.rs, utils.rs, misc.rs ou equivalentes so sao aceitaveis se houver justificativa objetiva e temporaria;
• testes devem morar onde a regra nasce, nao onde sobrou espaco.

Fora de Escopo

• alterar semantica da VM, scheduler, GC ou syscall ABI;
• redesenhar contratos publicos sem necessidade arquitetural real;
• reescrever o runtime inteiro de uma vez;
• mover codigo entre crates sem prova de que a fronteira de crate atual esta errada;
• reorganizacao cosmetica sem reducao de acoplamento.

Abordagem

1. Congelar as invariantes arquiteturais no documento canonico atual; se alguma extracao exigir mudanca de invariante, esta PR para e volta para discussao arquitetural.
2. Extrair primeiro a superficie de syscalls em prometeu-hal, porque ela define catalogo e metadata consumidos pelos outros lados.
3. Separar VirtualMachineRuntime em estado, lifecycle, tick e dispatch, preservando a API publica e o comportamento observavel.
4. Extrair a VM por blocos de maior densidade semantica: loader, execucao, GC, syscall ABI e stack helpers.
5. Migrar testes no mesmo passo da extracao:
   • teste de regra local fica adjacente ao modulo;
   • teste que cruza VM + runtime + bridge vira integracao.
6. A cada etapa, manter o diff comportamental pequeno e verificavel; modularizacao grande demais sem checkpoints tende a esconder regressao.

Criterios de Aceite

• Existe uma topologia aprovada para os tres monolitos principais: VM, runtime de sistema e syscalls.
• VirtualMachine, VirtualMachineRuntime e a API publica de syscalls continuam como facades claras, sem vazamento arbitrario de detalhes internos.
• Resolver de syscalls, dispatch de runtime e loop interno da VM deixam de conviver no mesmo arquivo monolitico de origem.
• A fronteira entre dominio, orquestracao e infraestrutura fica explicita em nomes de modulos e ownership.
• Testes sao redistribuidos com criterio:
  • unitario perto do modulo dono;
  • integracao para cruzamentos reais.
• Nenhuma etapa exige alteracao funcional da semantica atual para ser considerada concluida.

Tests

• Rodar suites existentes de prometeu-hal, prometeu-vm e prometeu-system a cada extracao relevante.
• Manter cobertura especifica para:
  • resolucao e metadata de syscalls;
  • init/load da VM;
  • traps/panics e traducao de faults no runtime;
  • GC e scheduler nos pontos de safepoint ja existentes.
• Adicionar ou promover testes de integracao quando a extracao cruzar crate boundary ou NativeInterface.
• Validar que a modularizacao nao muda API publica observavel nem quebra a arquitetura canonica documentada.

Risco

Medio. O risco principal e substituir um monolito explicito por varios modulos com ownership artificial, distribuindo acoplamento em vez de reduzi-lo. O antidoto aqui e simples: cada extracao precisa nascer com fronteira defensavel, testes no dono correto e facade central pequena. Sem isso, a PR nao deve avancar para implementacao.