created PR019
This commit is contained in:
parent
a6ad14fcb2
commit
ea12bd3fd5
SSH Key Fingerprint:
SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
@ -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.
|
|
||||||
@ -15,9 +15,6 @@ As agendas atuais são:
|
|||||||
- `003-structured-runtime-abi.md`
|
- `003-structured-runtime-abi.md`
|
||||||
- `004-syscall-fault-classification.md`
|
- `004-syscall-fault-classification.md`
|
||||||
- `005-runtime-edge-test-plan.md`
|
- `005-runtime-edge-test-plan.md`
|
||||||
- `006-break-monolith-runtime.md`
|
|
||||||
- `007-single-canonical-architecture.md`
|
|
||||||
- `008-hardware-specs-reorganization.md`
|
|
||||||
|
|
||||||
## Sequenciamento Recomendado
|
## Sequenciamento Recomendado
|
||||||
|
|
||||||
|
|||||||
@ -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.
|
|
||||||
@ -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.
|
||||||
Loading…
x
Reference in New Issue
Block a user