adjustments on docs

This commit is contained in:
2026-03-24 13:40:47 +00:00
parent f77b9f762f
commit 1b0e290e1d
42 changed files with 72 additions and 1655 deletions
@@ -0,0 +1,67 @@
# PR-013 [DEBUGGER]: Consume Structured Fault Events
## Briefing
O runtime e o host agora produzem `CrashReport` e emitem evento `fault` estruturado no protocolo do debugger. Mas o lado consumidor do DevTools ainda nao foi ajustado para tratar esse evento como dado de primeira classe. Sem isso, o debugger continua dependente de logs gerais ou de texto livre para exibir falhas da VM.
Esta PR fecha a ponta do debugger: faults estruturados passam a ser recebidos, armazenados e renderizados como diagnostico explicito, separado de logs e telemetria numerica.
## Problema
- o protocolo ja expõe `DebugEvent::Fault`, mas o cliente do debugger ainda pode ignorar esse evento;
- traps, panics e falhas de init continuam sem superficie dedicada no tooling;
- o operador do debugger nao consegue distinguir com clareza:
- log normal;
- violacao de certificacao;
- fault terminal da VM.
## Alvo
- cliente do debugger / DevTools que consome `DebugEvent`
- componentes de UI/estado que exibem logs, telemetria e status de execucao
- testes do lado cliente do debugger, se existirem no repo
## Escopo
- Consumir `DebugEvent::Fault` como evento estruturado, nao como log generico.
- Exibir pelo menos:
- tipo (`vm_trap`, `vm_panic`, `vm_init`);
- resumo;
- `pc`, quando existir;
- `trap_code` e `opcode`, quando existirem.
- Manter faults historicos recentes no estado do debugger de forma simples e deterministica.
- Garantir que um fault terminal fique visualmente distinguivel de log comum.
## Fora de Escopo
- Redesenhar toda a UI do debugger.
- Alterar novamente o protocolo do host, salvo ajuste minimo estritamente necessario.
- Implementar crash screen dentro da VM/firmware.
- Introduzir persistencia em disco de faults do debugger.
## Abordagem
1. Auditar o cliente do debugger e localizar onde `DebugEvent` e desserializado e roteado.
2. Adicionar tratamento explicito para `fault`, com estado proprio no cliente.
3. Renderizar o fault em area dedicada ou secao claramente separada de logs.
4. Preservar os campos estruturados; nenhuma logica deve depender de parsear `summary`.
5. Se houver historico, limitar o buffer de faults para manter simplicidade e previsibilidade.
## Criterios de Aceite
- O debugger reconhece `DebugEvent::Fault`.
- Um `VmTrap` aparece com `trap_code`, `opcode`, `pc` e resumo.
- Um `VmPanic` aparece distinto de `VmTrap`, sem depender de convencao textual.
- Um `VmInit` aparece distinto de fault de runtime.
- O fluxo de logs continua funcionando sem regressao.
## Tests
- Teste de desserializacao/roteamento do cliente cobrindo evento `fault`.
- Teste de estado/UI garantindo que `VmTrap` e `VmPanic` aparecem em superficie dedicada.
- Se houver suite de frontend/cliente, rodar a suite relevante do debugger.
- Se o cliente estiver no mesmo crate do host, incluir ao menos teste unitario do handler de eventos.
## Risco
Baixo a medio. O maior risco e introduzir uma segunda representacao local de fault que volte a colapsar semantica em texto. A implementacao deve reaproveitar o protocolo estruturado ja existente e manter a taxonomia pequena e estavel.
@@ -0,0 +1,80 @@
# PR-017 [ARCHITECTURE]: Establish Single Canonical Runtime Architecture
## Briefing
O runtime hoje tem mais de um documento tentando orientar a arquitetura, com niveis diferentes de autoridade e maturidade. Na pratica, isso cria um problema de governanca tecnica: contribuidores podem consultar documentos distintos, chegar a conclusoes diferentes e ainda assim parecer "alinhados com a arquitetura".
Esta PR fecha essa ambiguidade. O objetivo nao e produzir mais texto, e sim definir um unico documento canonico de arquitetura do runtime e rebaixar, fundir ou remover o que hoje compete com ele.
## Problema
- ha mais de um documento arquitetural relevante no repositorio;
- pelo menos um deles ainda se apresenta como `stub`, enquanto outro se declara baseline autoritativo;
- a fronteira entre:
- arquitetura normativa;
- roadmap;
- documento de apoio;
- material pedagogico;
nao esta explicitamente fechada;
- sem um documento canonico, a arquitetura deixa de ser guardrail e vira opiniao distribuida.
## Alvo
- documentos arquiteturais do runtime no raiz e em `docs/`;
- definicao de autoridade documental para runtime/VM/ABI/scheduler/GC/verifier;
- governanca minima para futuras PRs arquiteturais.
- todo conteudo em ingles.
-
## Escopo
- Escolher um unico documento canonico para a arquitetura do runtime.
- Definir o papel explicito dos demais documentos relacionados:
- canonico;
- derivado;
- historico;
- roadmap;
- pedagogico.
- Consolidar ou remover o documento `stub` que hoje compete com o baseline.
- Garantir que as invariantes arquiteturais centrais tenham um unico lar.
- Registrar a regra de manutencao: mudanca arquitetural exige atualizacao do documento canonico no mesmo PR.
## Fora de Escopo
- Reorganizar todo o diretorio `docs/`.
- Reescrever todas as specs detalhadas do projeto.
- Revisar estilo textual de todo material pedagogico.
- Introduzir mudancas comportamentais na VM, runtime ou firmware.
## Abordagem
1. Inventariar os documentos que hoje falam pela arquitetura do runtime.
2. Definir uma taxonomia minima de documentos para o repositorio:
- normativo;
- especificacao;
- roadmap;
- historico;
- pedagogico.
3. Escolher o documento canonico e migrar para ele apenas as invariantes que realmente governam o sistema.
4. Rebaixar, fundir ou remover o documento `stub` e qualquer outro texto que gere concorrencia de autoridade.
5. Deixar links e notas de transicao claros para evitar pontos cegos.
## Criterios de Aceite
- Existe exatamente um documento canonico de arquitetura do runtime.
- O papel dos demais documentos arquiteturais esta explicito.
- O documento `stub` deixa de competir por autoridade:
- removido; ou
- convertido em indice/redirecionamento sem ambiguidade.
- As invariantes centrais do runtime ficam localizadas no documento canonico.
- Fica documentada a regra de que PR arquitetural deve atualizar o documento canonico quando alterar invariantes.
## Tests
- Revisao estrutural dos links e referencias entre documentos afetados.
- Confirmacao manual de que nao restaram dois documentos com claims conflitantes de autoridade.
- Se a PR mover ou renomear arquivos, validar que referencias internas em `README`, `ARCHITECTURE` e `docs/` continuam corretas.
## Risco
Medio. O risco principal e produzir consolidacao superficial, deixando ambiguidade semantica mesmo depois da reorganizacao. A PR deve ser severa: se dois documentos ainda puderem ser lidos como "fonte final", a mudanca falhou.
@@ -0,0 +1,77 @@
# 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.
+35
View File
@@ -0,0 +1,35 @@
# Pull Requests
Este diretório armazena propostas de PRs arquiteturais e de implementação para o runtime.
## Padrão
Toda PR neste diretório deve ser autocontida.
Cada documento deve incluir, no mínimo:
- `Briefing`
- `Alvo`
- `Critérios de Aceite`
- `Tests`, quando necessário
## Barra de Qualidade
O padrão esperado é JVM-grade.
Isso implica:
- arquitetura vem antes de implementação;
- decisões arquiteturais não devem ser tomadas durante a fase de implementação;
- quando a implementação encontrar dúvida arquitetural, a PR deve voltar para discussão de arquitetura;
- diante de ambiguidade estrutural, é preferível interromper a execução da PR e levantar um questionamento severo do que cristalizar uma decisão errada no código.
## Condução
Uma PR deste diretório deve:
- definir claramente o problema;
- delimitar o alvo da mudança;
- explicitar o que está fora de escopo quando houver risco de expansão;
- estabelecer critérios objetivos de aceite;
- definir a estratégia de teste proporcional ao risco da mudança.