68 lines
3.0 KiB
Markdown
68 lines
3.0 KiB
Markdown
# 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.
|