62 lines
4.5 KiB
Markdown
62 lines
4.5 KiB
Markdown
---
|
|
id: DEC-0009
|
|
ticket: perf-host-debug-overlay-isolation
|
|
title: Decision - [PERF] Host Overlay Tooling Boundary
|
|
status: accepted
|
|
created: 2026-04-10
|
|
updated: 2026-04-10
|
|
agenda: AGD-0022
|
|
tags: [performance, host, gfx, overlay]
|
|
---
|
|
|
|
# Decision - [PERF] Host Overlay Tooling Boundary
|
|
|
|
## Status
|
|
**Accepted**
|
|
|
|
## Contexto
|
|
`DEC-0007` já determinou que o overlay técnico do desktop deve existir no Host e fora do pipeline de `gfx` emulado. Durante a execução, surgiu uma ambiguidade adicional: a implementação corretiva poderia ser interpretada como remoção ou desvalorização de `fill_rect` e `draw_text`, quando essas primitives continuam fazendo parte legítima do contrato gráfico atual da máquina emulada.
|
|
|
|
Também ficou explícito que “estar no host” não é suficiente se o overlay ainda desenhar usando `hardware.gfx`. O limite correto é mais estrito: o overlay deve possuir ferramentas próprias e compor em camada separada no host.
|
|
|
|
## Decisao
|
|
Fica decidido que o contrato do overlay técnico do desktop host será refinado da seguinte forma:
|
|
|
|
1. **Preservação do Contrato Emulado:** `fill_rect` e `draw_text` MUST remain part of the current syscall and emulated hardware contract. They MUST NOT be removed, weakened, or repurposed because of host overlay work.
|
|
2. **Separação de Ferramentas:** O overlay técnico do desktop host MUST use dedicated host-side tooling for panel composition, text rendering, simple bars, and alert presentation.
|
|
3. **Proibição de Dependência do Hardware Emulado:** O overlay MUST NOT call, depend on, or route through `hardware.gfx`, `fill_rect`, `draw_text`, or any equivalent emulated-framebuffer primitive.
|
|
4. **Camada Separada no Host:** O overlay MUST be rendered in a separate host layer/surface after the emulated frame is produced. The emulated framebuffer MAY be transported into the host presentation surface, but overlay pixels MUST NOT be written back into the emulated framebuffer.
|
|
5. **Módulo Dedicado:** A dedicated host module SHALL own overlay rendering behavior. The implementation MUST NOT remain embedded as ad hoc overlay drawing logic inside `runner.rs`.
|
|
6. **Escopo Visual Mínimo:** Para este ciclo, o overlay SHOULD remain intentionally simple: semitransparent panel, text, and simple bars where useful. It MUST NOT introduce a general UI framework, docking model, or movable window system.
|
|
7. **Responsabilidade do Runtime:** O runtime MUST remain responsible only for telemetry exposure and inspection state gating. It MUST NOT own overlay drawing behavior, layout policy, or visual composition.
|
|
|
|
## Rationale
|
|
- **Clareza de Fronteira:** Preservar o contrato da máquina e mover apenas o overlay evita misturar API emulada com inspeção técnica de host.
|
|
- **Pureza do Framebuffer:** Uma camada separada elimina a contaminação visual do framebuffer emulado e torna a validação objetiva.
|
|
- **Simplicidade Controlada:** Texto e barras simples resolvem legibilidade sem transformar o host overlay em um projeto paralelo de UI.
|
|
- **Manutenibilidade:** Um módulo dedicado reduz o risco de regressão arquitetural em `runner.rs`.
|
|
|
|
## Invariantes / Contrato
|
|
- `fill_rect` e `draw_text` continuam válidos para o domínio emulado.
|
|
- O overlay técnico do host não escreve no framebuffer emulado.
|
|
- O overlay técnico do host não depende de primitives do hardware emulado.
|
|
- O módulo de overlay é de responsabilidade exclusiva do host desktop.
|
|
- O ponto de composição do overlay ocorre depois que o frame emulado já está pronto para apresentação no host.
|
|
|
|
## Impactos
|
|
- **Host (Desktop Winit):** Exige um módulo próprio de overlay e uma estratégia de composição em camada separada.
|
|
- **Runtime API:** Nenhuma mudança conceitual adicional além de continuar expondo telemetria passiva e gating de inspeção.
|
|
- **Specs:** As especificações de debug e portabilidade devem distinguir explicitamente o contrato emulado das ferramentas de overlay do host.
|
|
- **Plano de Execução:** `PLN-0008` deve ser atualizado para refletir módulo dedicado e camada separada no host.
|
|
|
|
## Referencias
|
|
- `AGD-0022`: [PERF] Host Overlay Tooling Boundary Revision.
|
|
- `DEC-0007`: [PERF] Host Debug Overlay Isolation.
|
|
- `DEC-0008`: Full Migration to Atomic Telemetry.
|
|
|
|
## Propagacao Necessaria
|
|
1. Atualizar `PLN-0008` para refletir o módulo dedicado e a camada separada no host.
|
|
2. Implementar o módulo de overlay no `prometeu-host-desktop-winit`.
|
|
3. Remover o uso de `hardware.gfx` pelo overlay técnico.
|
|
4. Atualizar as specs para preservar o contrato gráfico emulado e separar a composição do overlay host.
|