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:

fill_rect e draw_text permanecem intactos como parte do contrato atual de syscall e do hardware emulado.
O overlay técnico do desktop host não pode chamar nem depender dessas primitives do hardware.gfx.
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.
O runtime continua responsável apenas por telemetria e sinais de inspeção, nunca por desenho do overlay.
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)

5.2 KiB Raw Blame History