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:

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.
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.
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.
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.
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.
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.
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

Atualizar PLN-0008 para refletir o módulo dedicado e a camada separada no host.
Implementar o módulo de overlay no prometeu-host-desktop-winit.
Remover o uso de hardware.gfx pelo overlay técnico.
Atualizar as specs para preservar o contrato gráfico emulado e separar a composição do overlay host.

4.5 KiB Raw Blame History