diff --git a/docs/runtime/agendas/006-break-monolith-runtime.md b/docs/runtime/agendas/006-break-monolith-runtime.md deleted file mode 100644 index 80c5f63b..00000000 --- a/docs/runtime/agendas/006-break-monolith-runtime.md +++ /dev/null @@ -1,87 +0,0 @@ -# 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. diff --git a/docs/runtime/agendas/README.md b/docs/runtime/agendas/README.md index c1fb61a8..4cd0cbfe 100644 --- a/docs/runtime/agendas/README.md +++ b/docs/runtime/agendas/README.md @@ -15,9 +15,6 @@ As agendas atuais são: - `003-structured-runtime-abi.md` - `004-syscall-fault-classification.md` - `005-runtime-edge-test-plan.md` -- `006-break-monolith-runtime.md` -- `007-single-canonical-architecture.md` -- `008-hardware-specs-reorganization.md` ## Sequenciamento Recomendado diff --git a/docs/runtime/pull-requests/PR-018-[SPECS]-reorganize-hardware-specification-surface.md b/docs/runtime/pull-requests/PR-018-[SPECS]-reorganize-hardware-specification-surface.md deleted file mode 100644 index 468851f2..00000000 --- a/docs/runtime/pull-requests/PR-018-[SPECS]-reorganize-hardware-specification-surface.md +++ /dev/null @@ -1,77 +0,0 @@ -# PR-018 [SPECS]: Reorganize Hardware Specification Surface - -## Briefing - -As specs de hardware e sistema acumuladas no repositorio contem material valioso, mas a organizacao atual esta irregular. Hoje convivem no mesmo pacote temas de perifericos, VM, firmware, cartridge, assets e host ABI, com pesos muito diferentes entre si e sem uma separacao suficientemente clara entre conteudo normativo e conteudo pedagogico. - -Esta PR nao pretende reescrever toda a especificacao. Ela existe para organizar a superficie documental, definir taxonomia e preparar o terreno para futuras PRs de conteudo sem perpetuar a colcha de retalhos atual. - -## Problema - -- o pacote de specs atual mistura dominios heterogeneos sob a mesma superficie de "hardware"; -- ha capitulos extensos e narrativos convivendo com material que deveria ser normativo; -- ownership documental por area nao esta claro; -- a navegacao esta fraca para quem precisa alterar apenas um dominio tecnico; -- o risco de contradicao entre spec, arquitetura e implementacao cresce a cada novo remendo. - -## Alvo - -- `docs/specs/hardware/` e sua organizacao atual; -- relacao entre specs de hardware, arquitetura de runtime, firmware, cartridge, assets e host ABI; -- indice e taxonomia documental das specs tecnicas. - -## Escopo - -- Definir uma taxonomia clara para as specs tecnicas do projeto, por exemplo: - - machine/runtime; - - hardware/peripherals; - - firmware/system; - - cartridge/package; - - host ABI; - - assets/tooling. -- Decidir o que realmente pertence ao pacote de "hardware" e o que deve migrar para outra categoria. -- Propor uma nova arvore de organizacao e navegacao para as specs. -- Mapear os capitulos atuais para seus destinos futuros. -- Explicitar o que e: - - normativo; - - explicativo; - - historico; - - pedagogico. - -## Fora de Escopo - -- Reescrever tecnicamente todos os capitulos. -- Atualizar o conteudo detalhado de cada spec nesta mesma PR. -- Alterar a arquitetura do runtime por meio de reorganizacao documental. -- Normalizar todo estilo editorial do repositorio. - -## Abordagem - -1. Inventariar a estrutura atual das specs e classificar cada documento por dominio e funcao. -2. Definir uma taxonomia pequena, defensavel e duravel para as specs do projeto. -3. Desenhar a arvore alvo de diretorios e indices. -4. Mapear capitulo atual -> destino futuro, explicitando: - - permanece; - - move; - - divide; - - funde; - - vira historico. -5. Ajustar a navegacao minima para que a reorganizacao nao deixe o leitor sem trilha. - -## Criterios de Aceite - -- Existe uma taxonomia aprovada para as specs tecnicas. -- A organizacao alvo de diretorios e indices esta definida. -- Cada capitulo atual relevante tem destino planejado. -- A separacao entre conteudo normativo e pedagogico fica explicita. -- O pacote de "hardware" deixa de ser deposito generico de temas nao relacionados. - -## Tests - -- Revisao manual da navegacao entre indice principal, README das specs e topicos afetados. -- Confirmacao de que a nova organizacao nao cria links quebrados nos pontos principais do repositorio. -- Validacao de que a taxonomia proposta e coerente com o documento canonico de arquitetura. - -## Risco - -Medio. O risco principal e trocar a desordem atual por uma reorganizacao cosmetica sem criterio de autoridade nem ownership. A PR deve sair com taxonomia clara e mapa de migracao; sem isso, sera apenas renomeacao de pastas. 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 new file mode 100644 index 00000000..2c4cf4b1 --- /dev/null +++ b/docs/runtime/pull-requests/PR-019-[RUNTIME]-break-monolith-runtime.md @@ -0,0 +1,150 @@ +# 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.