---
id: AGD-0022
ticket: perf-host-debug-overlay-isolation
title: Agenda - [PERF] Host Overlay Tooling Boundary Revision
status: accepted
created: 2026-04-10
resolved: 2026-04-10
decision: DEC-0009
tags: [performance, host, gfx, overlay]
---

# Agenda - [PERF] Host Overlay Tooling Boundary Revision

## Contexto

`DEC-0007` fechou o movimento do overlay de debug para o `Host Desktop`, fora do runtime e fora do pipeline de `gfx` emulado. Durante a execução, a formulação acabou ficando forte demais em um ponto: passou a sugerir que `fill_rect` e `draw_text` deveriam deixar de existir no contrato atual, quando na verdade o usuário quer preservar essas ferramentas como parte válida do contrato de syscall atual.

O ajuste pedido agora é mais específico:
- `fill_rect` e `draw_text` permanecem como parte do contrato atual da máquina e continuam disponíveis para uso legítimo do software emulado;
- o overlay técnico de host não pode depender desse caminho;
- o overlay deve possuir ferramentas próprias para compor o que for necessário no host, fora do `hardware.gfx`.

## Problema

Sem registrar essa revisão, a execução fica ambígua em dois pontos:
- podemos remover ou enfraquecer APIs gráficas que não deveriam ser tocadas;
- podemos continuar interpretando o overlay host como “qualquer desenho fora do runtime”, mesmo se ele ainda reutilizar primitives do hardware emulado.

O resultado é ruído entre contrato da máquina, contrato do host, e ferramentas de inspeção.

## Pontos Criticos

- **Fato:** O overlay continua sendo exclusivo do host desktop.
- **Fato:** `fill_rect` e `draw_text` fazem parte do contrato atual de syscall e não devem ser removidos por causa do overlay.
- **Risco:** Se o host overlay continuar apoiado em `hardware.gfx`, ele continua contaminando o framebuffer emulado.
- **Risco:** Se criarmos “tools próprias” sem delimitar bem a fronteira, podemos introduzir um mini-subsistema paralelo sem contrato claro.
- **Tradeoff:** Preservar o contrato atual da máquina simplifica compatibilidade, mas exige um caminho de composição separado no host para não misturar domínio emulado com inspeção técnica.

## Opcoes

- **Opção A (Recomendada):** Preservar `fill_rect`/`draw_text` como contrato do hardware emulado e criar um conjunto de ferramentas nativas do host para o overlay.
  - O overlay passa a usar renderer/layout/composição próprios do host.
  - O runtime continua apenas expondo dados.
  - O `hardware.gfx` fica reservado ao conteúdo da máquina emulada.

- **Opção B:** Generalizar `fill_rect`/`draw_text` para servirem também ao host overlay.
  - Reaproveita código existente.
  - Mantém o acoplamento semântico entre overlay técnico e hardware emulado.
  - Dificulta provar pureza do framebuffer.

- **Opção C:** Criar novas syscalls específicas de overlay no runtime.
  - Formaliza ferramentas novas, mas empurra responsabilidade de inspeção para dentro da máquina.
  - Viola a direção de host-only já aceita e reabre debate maior do que o necessário.

## Sugestao / Recomendacao

Seguir com a **Opção A** e revisar a decisão operacional nestes termos:

1. `fill_rect` e `draw_text` permanecem intactos como parte do contrato atual de syscall e do hardware emulado.
2. O overlay técnico do desktop host não pode chamar nem depender dessas primitives do `hardware.gfx`.
3. O host deve ter ferramentas próprias de overlay, com responsabilidades explícitas:
   - montagem dos dados exibidos;
   - layout do painel;
   - rasterização/composição nativa;
   - controle visual de transparência e tipografia.
4. O runtime continua responsável apenas por telemetria e sinais de inspeção, nunca por desenho do overlay.
5. A validação precisa provar dois limites:
   - o contrato gráfico emulado continua disponível;
   - o overlay técnico não escreve no framebuffer emulado.

Para este ciclo, o overlay deve permanecer deliberadamente simples:
- painel semitransparente;
- texto para métricas e estados;
- barras básicas para uso relativo de orçamento/capacidade quando isso melhorar leitura;
- sem badges decorativos, widgets complexos, docking, janelas móveis, ou mini-framework de UI.

Essa direção preserva o objetivo principal do ticket, que é a fronteira arquitetural correta, sem transformar o host overlay em um projeto próprio.

## Perguntas em Aberto

- A implementação deve ficar embutida em `runner.rs` inicialmente ou nascer como módulo dedicado (`overlay.rs`) desde o começo?
- A composição será feita diretamente no buffer final do `pixels` ou via camada/render pass separada dentro do host?
Nenhuma. Em 2026-04-10 foi acordado:
- módulo dedicado para o overlay;
- camada separada no host;
- sem blit do overlay no framebuffer emulado;
- o framebuffer emulado pode ser transportado para a surface/camada de overlay do host, nunca o contrário.

## Criterio para Encerrar

Esta agenda pode ser encerrada quando houver consenso explícito sobre:
- preservação de `fill_rect` e `draw_text` no contrato atual;
- proibição de uso dessas primitives pelo overlay técnico;
- conjunto mínimo de ferramentas próprias do overlay no host;
- ponto exato de composição no pipeline do desktop host.
*(Critérios atingidos em 2026-04-10)*