From af8f4304b955f06a801bb93cbed7828999cac343 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Tue, 3 Mar 2026 16:42:38 +0000 Subject: [PATCH] break monster VM into small pieces :D --- ...PR-019-[RUNTIME]-break-monolith-runtime.md | 150 ------------------ 1 file changed, 150 deletions(-) delete mode 100644 docs/runtime/pull-requests/PR-019-[RUNTIME]-break-monolith-runtime.md diff --git a/docs/runtime/pull-requests/PR-019-[RUNTIME]-break-monolith-runtime.md b/docs/runtime/pull-requests/PR-019-[RUNTIME]-break-monolith-runtime.md deleted file mode 100644 index 2c4cf4b1..00000000 --- a/docs/runtime/pull-requests/PR-019-[RUNTIME]-break-monolith-runtime.md +++ /dev/null @@ -1,150 +0,0 @@ -# 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.