[PERF] Host Debug Overlay Isolation
This commit is contained in:
@@ -0,0 +1,64 @@
|
||||
---
|
||||
id: PLN-0006
|
||||
ticket: perf-host-debug-overlay-isolation
|
||||
title: PR/Plan - [PERF] Host Debug Overlay Isolation
|
||||
status: open
|
||||
created: 2026-04-10
|
||||
updated: 2026-04-10
|
||||
decisions: [DEC-0007]
|
||||
tags: [performance, host, gfx]
|
||||
---
|
||||
|
||||
# PR/Plan - [PERF] Host Debug Overlay Isolation
|
||||
|
||||
## Briefing
|
||||
Implementação do isolamento total do overlay de debug no Host Desktop (`prometeu-host-desktop-winit`), removendo o acoplamento com o runtime e o pipeline de `gfx` emulado.
|
||||
|
||||
## Decisions de Origem
|
||||
- `DEC-0007`: [PERF] Host Debug Overlay Isolation.
|
||||
- `DEC-0005`: [PERF] Push-based Telemetry Model (base para extração de dados).
|
||||
|
||||
## Alvo
|
||||
- `crates/host/prometeu-host-desktop-winit`: Implementação da camada nativa de HUD.
|
||||
- `crates/runtime`: Exposição de campos de telemetria via API.
|
||||
- `docs/specs/runtime`: Atualização das especificações de debug e portabilidade.
|
||||
|
||||
## Escopo
|
||||
- **Spec Work:**
|
||||
- Atualizar `docs/specs/runtime/10-debug-inspection-and-profiling.md` para remover menções ao HUD emulado.
|
||||
- Atualizar `docs/specs/runtime/11-portability-and-cross-platform-execution.md` para reforçar a separação de responsabilidades (Host-side HUD).
|
||||
- **Code Work:**
|
||||
- Expansão da API de telemetria no runtime para incluir todos os dados necessários (Cycles, Memory, Logs).
|
||||
- Remoção do código de desenho de texto legado no `runner.rs`.
|
||||
- Integração de biblioteca nativa (ex: `egui` ou composição via `pixels`) para renderização do novo overlay no Host.
|
||||
- Implementação do toggle via tecla **F1** no `HostRunner`.
|
||||
|
||||
## Fora de Escopo
|
||||
- Implementação de overlay visual em outros hosts (mobile, handheld).
|
||||
- Alterações na lógica de emulação central (loop de execução).
|
||||
|
||||
## Plano de Execucao
|
||||
1. **Fase 1: Especificações (Spec)**
|
||||
- Revisar e atualizar os arquivos de especificação (`10-debug` e `11-portability`).
|
||||
2. **Fase 2: Runtime Telemetry API (Code)**
|
||||
- Garantir que todos os campos de telemetria estejam expostos via atômicos/push-based conforme `DEC-0005`.
|
||||
3. **Fase 3: Host HUD Implementation (Code)**
|
||||
- Integrar o novo motor de HUD no `prometeu-host-desktop-winit`.
|
||||
- Conectar os dados da API de telemetria à visualização do HUD.
|
||||
4. **Fase 4: Cleanup (Code)**
|
||||
- Remover hotspots de formatação de strings e draw calls do overlay antigo no Host.
|
||||
|
||||
## Criterios de Aceite
|
||||
- O overlay de debug é ativado/desativado via tecla **F1**.
|
||||
- O overlay utiliza fontes TrueType (monospaced) nítidas e fundo semi-transparente.
|
||||
- O framebuffer emulado não contém pixels do HUD (composição nativa pós-upscaling).
|
||||
- O custo de ciclos do runtime é idêntico com o overlay ligado ou desligado.
|
||||
|
||||
## Tests / Validacao
|
||||
- **Verificação Visual:** Confirmar a qualidade das fontes e a transparência do novo HUD.
|
||||
- **Benchmarking:** Comparar os ciclos consumidos por frame com e sem o HUD ativo para provar isolamento.
|
||||
- **Teste de Regressão:** Garantir que o F1 toggle não afeta a estabilidade do loop de emulação.
|
||||
|
||||
## Riscos
|
||||
- **Overhead no Host:** A renderização nativa (ex: `egui`) pode introduzir overhead no Host Desktop em máquinas muito fracas (geralmente aceitável em Desktop).
|
||||
- **Sincronização de Telemetria:** Pequeno atraso visual entre o frame renderizado e os dados exibidos se a coleta for puramente assíncrona (aceitável para telemetria de debug).
|
||||
@@ -0,0 +1,52 @@
|
||||
# PLN-0007: Full Migration to Atomic Telemetry
|
||||
|
||||
## Briefing
|
||||
Este plano detalha a remoção técnica dos campos legados de telemetria no `VirtualMachineRuntime` e a migração de todos os consumidores para o modelo de `AtomicTelemetry` introduzido na DEC-0007.
|
||||
|
||||
## Decisions de Origem
|
||||
- DEC-0008 (Full Migration to Atomic Telemetry)
|
||||
- DEC-0007 (Host Debug Overlay Isolation)
|
||||
|
||||
## Alvo
|
||||
- `crates/console/prometeu-system`
|
||||
- `crates/console/prometeu-hal`
|
||||
- `crates/host/prometeu-host-desktop-winit`
|
||||
|
||||
## Escopo
|
||||
- Remoção de `telemetry_current` e `telemetry_last` de `VirtualMachineRuntime`.
|
||||
- Refatoração do `VirtualMachineRuntime::tick` para remover atualizações redundantes.
|
||||
- Atualização do `VirtualMachineRuntime::lifecycle` para remover inicialização e reset dos campos legados.
|
||||
- Refatoração do `LogService` para consumir logs via `AtomicTelemetry`.
|
||||
- Atualização do `HostRunner` (Desktop) para remover qualquer referência residual aos campos legados.
|
||||
- Atualização das especificações técnicas em `docs/specs/runtime/`.
|
||||
|
||||
## Fora de Escopo
|
||||
- Mudanças no formato do `TelemetryFrame` (a menos que estritamente necessário para compatibilidade).
|
||||
- Otimizações de performance não relacionadas à telemetria.
|
||||
|
||||
## Plano de Execucao
|
||||
1. **Fase 1: HAL & Telemetry**
|
||||
- Verificar se `AtomicTelemetry` possui todos os campos necessários.
|
||||
- Garantir que `LogService` está alinhado com o novo modelo.
|
||||
2. **Fase 2: Runtime Refactor**
|
||||
- Remover campos de `VirtualMachineRuntime` em `mod.rs`.
|
||||
- Limpar inicialização em `lifecycle.rs`.
|
||||
- Limpar loop de atualização em `tick.rs`.
|
||||
3. **Fase 3: Host & Integration**
|
||||
- Corrigir chamadas no `HostRunner` que ainda usem os campos antigos.
|
||||
- Validar que o snapshot atômico atende às necessidades de inspeção.
|
||||
4. **Fase 4: Specs & Cleanup**
|
||||
- Atualizar `10-debug` e `11-portability`.
|
||||
- Emitir lição aprendida LSN-0028.
|
||||
|
||||
## Criterios de Aceite
|
||||
- O projeto compila sem warnings relacionados a campos não utilizados.
|
||||
- O Host Desktop inicia e o overlay (F1) exibe telemetria correta via atômicos.
|
||||
- Não existem mais os campos `telemetry_current` e `telemetry_last` no código fonte.
|
||||
|
||||
## Tests / Validacao
|
||||
- `cargo check` em todos os crates afetados.
|
||||
- Execução manual do host desktop para validar overlay.
|
||||
|
||||
## Riscos
|
||||
- **Perda de Snapshot de Frame:** Se o `snapshot()` não for chamado no momento certo ao final do frame, o overlay pode mostrar valores parciais de ciclos (resolvido chamando `snapshot()` no Host no momento de renderização do overlay).
|
||||
Reference in New Issue
Block a user