clean up
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good

This commit is contained in:
2026-04-10 23:38:20 +01:00
parent 8f98aee64e
commit 70cde0d975
12 changed files with 1 additions and 689 deletions
@@ -1,64 +0,0 @@
---
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).
@@ -1,52 +0,0 @@
# 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).
@@ -1,144 +0,0 @@
---
id: PLN-0008
ticket: perf-host-debug-overlay-isolation
title: PR/Plan - Host Overlay Native Composition Alignment
status: in_progress
created: 2026-04-10
completed:
tags: [performance, host, gfx, telemetry]
---
## Objective
Bring the desktop debug overlay implementation back into compliance with `DEC-0007`, `DEC-0009`, and `DEC-0010` by keeping the overlay in the host layer while rendering it in a dedicated host module and separate host layer, outside the emulated hardware framebuffer and outside `hardware.gfx`.
## Background
`DEC-0007` requires the debug overlay to be a host-only layer composed after the emulated frame is complete. `DEC-0009` further clarifies that `fill_rect` and `draw_text` remain part of the emulated machine contract, but the host overlay must not depend on them and must live in a dedicated host module and separate host layer. `DEC-0010` fixes the semantics of the visible `LOGS` metric so the Host overlay reads the last completed frame value instead of a transient intra-frame counter.
The current `HostRunner` still calls `hardware.gfx.fill_rect()` and `hardware.gfx.draw_text()` for the overlay, which means the HUD is still being injected into the emulated graphics path even though its data source already comes from `AtomicTelemetry`.
`PLN-0007` completed the telemetry migration, so the remaining gap is no longer data access. The remaining gap is presentation architecture in the desktop host.
## Scope
### Included
- Remove all overlay rendering calls that write through `hardware.gfx`.
- Introduce a desktop-host-native overlay composition path in `prometeu-host-desktop-winit`.
- Implement the overlay in a dedicated host module instead of ad hoc logic inside `runner.rs`.
- Keep overlay visibility and lifecycle fully controlled by the desktop host.
- Continue reading inspection data through `AtomicTelemetry::snapshot()` and host-side log access.
- Expose `LOGS` to the overlay as the last completed logical frame value.
- Update runtime specifications so they explicitly state that the overlay is host-native and not part of the emulated machine framebuffer.
- Add verification that enabling the overlay does not mutate emulated pixels.
### Excluded
- Adding overlays to non-desktop hosts.
- Reopening the telemetry model or changing `TelemetryFrame` semantics.
- Reworking unrelated presentation, frame pacing, debugger transport, or certification behavior.
## Execution Steps
### Step 1 - Extract overlay responsibilities into a dedicated host module
**What:**
Move overlay formatting, layout, and drawing responsibilities out of `runner.rs` and into a dedicated host module.
**How:**
Create a dedicated module such as `overlay.rs` that owns host overlay data preparation, panel layout, simple bars, and text rendering. `runner.rs` should orchestrate visibility and presentation only. The new module must never call emulated graphics primitives.
**File(s):**
- `crates/host/prometeu-host-desktop-winit/src/runner.rs`
- `crates/host/prometeu-host-desktop-winit/src/stats.rs`
- `crates/host/prometeu-host-desktop-winit/src/overlay.rs`
### Step 2 - Compose the overlay in a separate host layer
**What:**
Ensure the overlay is rendered in a separate host layer/surface and never blitted into the emulated framebuffer.
**How:**
Preserve the `F1` toggle in `HostRunner`, keep telemetry reads on the host side, and present the overlay after the emulated frame is already ready for display. The implementation may transport the emulated framebuffer into the host presentation surface, but the overlay must remain a separate host composition step and must not write back into `hardware.gfx`.
**File(s):**
- `crates/host/prometeu-host-desktop-winit/src/runner.rs`
- `crates/host/prometeu-host-desktop-winit/src/overlay.rs`
### Step 3 - Add regression coverage for framebuffer purity
**What:**
Add tests or deterministic checks that prove the overlay no longer modifies emulated graphics output.
**How:**
Cover the overlay toggle and composition boundary with focused host tests where practical. At minimum, add a test seam or helper that lets the host render path be exercised without requiring overlay drawing through `hardware.gfx`. If a full automated framebuffer assertion is not practical yet, add a narrow unit test around the new composition entry point plus manual verification instructions that compare raw emulated output with overlay enabled and disabled.
**File(s):**
- `crates/host/prometeu-host-desktop-winit/src/runner.rs`
- `crates/host/prometeu-host-desktop-winit/src/overlay.rs`
- `crates/host/prometeu-host-desktop-winit/src/tests.rs` or existing test module location
### Step 4 - Align log metric semantics with frame-end snapshots
**What:**
Ensure the visible `LOGS` metric represents the last completed frame instead of a transient in-flight counter.
**How:**
Persist the completed-frame log count into `AtomicTelemetry` before resetting the transient `LogService` counter. Keep certification evaluation and host overlay consumption aligned on that persisted frame-end value.
**File(s):**
- `crates/console/prometeu-hal/src/log/log_service.rs`
- `crates/console/prometeu-hal/src/telemetry.rs`
- `crates/console/prometeu-system/src/virtual_machine_runtime/tick.rs`
- `crates/host/prometeu-host-desktop-winit/src/overlay.rs`
### Step 5 - Update normative documentation
**What:**
Align specs and workflow artifacts with the corrected execution path.
**How:**
Update the runtime debug and portability specifications to explicitly say the overlay is desktop-host-native, post-upscaling, and outside the emulated framebuffer. Keep the discussion workflow aligned by referencing this corrective plan during execution and closure.
**File(s):**
- `docs/specs/runtime/10-debug-inspection-and-profiling.md`
- `docs/specs/runtime/11-portability-and-cross-platform-execution.md`
## Test Requirements
### Unit Tests
- Host overlay toggle logic remains host-owned and does not require `hardware.gfx` text drawing.
- New host-native overlay composition entry point can format and present telemetry without mutating the emulated framebuffer abstraction.
- Simple bars and text layout are owned by the dedicated host overlay module.
### Integration Tests
- `cargo check` for `prometeu-host-desktop-winit`, `prometeu-system`, and any touched supporting crate.
- If automated host rendering tests are feasible, verify an emulated frame buffer dump is identical with overlay off and overlay on before the host-only composition stage.
### Manual Verification
- Run the desktop host, toggle `F1`, and confirm the overlay appears and disappears correctly.
- Capture or inspect the emulated framebuffer path and confirm no HUD pixels are written into machine output.
- Confirm telemetry values still update through `AtomicTelemetry`.
## Acceptance Criteria
- [ ] No desktop overlay code writes through `hardware.gfx.fill_rect`, `hardware.gfx.draw_text`, or equivalent emulated-machine drawing APIs.
- [ ] `fill_rect` and `draw_text` remain intact as part of the emulated graphics contract and are not repurposed for host overlay rendering.
- [ ] The desktop overlay remains controlled by `HostRunner` and uses host-side telemetry snapshots.
- [ ] The visible overlay is composed in a separate host layer after the emulated frame and is not burned into the emulated framebuffer.
- [ ] Runtime telemetry remains gated by inspection state and continues to function for overlay consumption.
- [ ] The visible `LOGS` metric represents the last completed logical frame.
- [ ] Specs describe the overlay as host-native and outside the emulated hardware contract.
## Dependencies
- `DEC-0007` accepted and unchanged.
- `DEC-0008` accepted and unchanged.
- `DEC-0009` accepted and unchanged.
- `DEC-0010` accepted and unchanged.
- Existing `AtomicTelemetry` host snapshot path remains available.
## Risks
- Desktop-native text and alpha composition may require extra host rendering plumbing that is more complex than the previous `hardware.gfx` path.
- Without an explicit test seam, it is easy to accidentally reintroduce overlay writes into the emulated graphics path during future host refactors.
- Host composition cost may rise slightly, but that cost is acceptable as long as it remains outside runtime cycle accounting.