[PERF] Host Debug Overlay Isolation

This commit is contained in:
2026-04-10 10:55:15 +01:00
parent f5580ae0ce
commit 47ab664280
21 changed files with 526 additions and 154 deletions
@@ -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).