[PERF] Host Debug Overlay Isolation

This commit is contained in:
2026-04-10 14:10:20 +01:00
parent b8d33c9e02
commit 58a5f9a3a6
18 changed files with 1315 additions and 123 deletions
@@ -0,0 +1,96 @@
---
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)*
@@ -0,0 +1,53 @@
---
id: AGD-0023
ticket: perf-host-debug-overlay-isolation
title: Agenda - [PERF] Overlay Log Metric Must Show Last Frame
status: accepted
created: 2026-04-10
resolved: 2026-04-10
decision: DEC-0010
tags: [performance, host, telemetry, logs]
---
# Agenda - [PERF] Overlay Log Metric Must Show Last Frame
## Contexto
Após mover o overlay para a camada de Host, o campo visual `LOGS` passou a expor um contador transitório compartilhado com o `LogService`. Esse contador é incrementado durante o frame e zerado no fechamento do frame lógico. Na prática, quando o Host lê a telemetria para desenhar o overlay, o valor visual tende a aparecer como `0`, mesmo em cenários com alta emissão de logs.
## Problema
O campo `LOGS` no overlay não está representando a informação útil para inspeção visual. Um valor transitório intra-frame é adequado para coleta interna, mas não para HUD técnico renderizado assíncronamente pelo Host.
## Pontos Criticos
- **Fato:** O Host lê a telemetria fora do momento exato em que o contador transitório atinge seu pico.
- **Fato:** A certificação precisa continuar vendo a pressão de logs do frame completo.
- **Risco:** Manter a semântica atual torna o campo visual enganoso e inutilizável.
- **Tradeoff:** Precisamos preservar o contador transitório para coleta interna, mas expor ao overlay apenas um valor persistido do último frame fechado.
## Opcoes
- **Opção A (Recomendada):** Persistir `logs from last completed frame` no `AtomicTelemetry` e fazer o overlay ler apenas esse valor.
- **Opção B:** Manter contador ao vivo e tentar amostrar em outro ponto do loop.
- **Opção C:** Mostrar ambos os valores no overlay.
## Sugestao / Recomendacao
Seguir com a **Opção A**:
1. O contador transitório de logs continua existindo apenas para coleta interna durante o frame.
2. No fechamento do frame lógico, o runtime persiste em `AtomicTelemetry` o total de logs do frame recém-concluído.
3. O campo `LOGS` visível no overlay deve representar exclusivamente `logs from last completed frame`.
4. A certificação deve continuar operando sobre esse mesmo valor persistido do frame concluído.
## Perguntas em Aberto
- Nenhuma. Em 2026-04-10 foi decidido que o overlay deve mostrar apenas logs do último frame concluído.
## Criterio para Encerrar
- semântica visual de `LOGS` definida como `last completed frame`;
- certificação preservada;
- implementação alinhada no HAL, runtime, overlay e specs.
*(Critérios atingidos em 2026-04-10)*
@@ -0,0 +1,147 @@
---
id: AGD-0024
ticket: generic-memory-bank-slot-contract
title: Agenda - Generic Memory Bank Slot Contract
status: accepted
created: 2026-04-10
resolved: 2026-04-10
decision: DEC-0012
tags: [runtime, asset, memory-bank, slots, host]
---
# Agenda - Generic Memory Bank Slot Contract
## Contexto
Hoje o runtime e o host expõem bancos de memória principalmente pela ótica de bytes totais/usados, enquanto a organização real do hardware já é fortemente orientada a slots. No estado atual:
- `GFX` e `AUD` aparecem como casos especiais espalhados entre `AssetManager`, `MemoryBanks`, `AssetBridge`, telemetria e overlay;
- os pools concretos são específicos (`glyph_bank_pool`, `sound_bank_pool`);
- a visualização do overlay precisou reinterpretar um modelo em bytes para algo que, operacionalmente, é mais bem entendido como ocupação de slots.
O pedido do usuário é explicitamente mudar essa ênfase: manter bytes como detalhe secundário quando necessário, mas estruturar o modelo principal como **memory banks by slots**, com possibilidade de contrato específico no domínio de `MemoryBanks` para gerir esses valores.
Na continuação da discussão, o usuário endureceu a direção:
- `BankPolicy` deve ser removido por completo;
- `BankStats` deve ser removido por completo;
- o contrato exposto deve trabalhar somente com ocupação por slots, por exemplo:
- `glyph_slots_occupied / glyph_slots.len()`
- `sound_slots_occupied / sound_slots.len()`
## Problema
O modelo atual mistura dois níveis de abstração:
1. **Contrato de capacidade em bytes**, útil para certificação e budgets;
2. **Contrato operacional por slots**, que é o que o host e o programador realmente percebem ao lidar com banks.
Isso gera acoplamento e duplicação:
- o domínio conhece `GFX` e `AUD` como exceções, em vez de bancos genéricos com propriedades próprias;
- `BankStats` privilegia bytes e trata slots como apêndice;
- `MemoryBanks` não oferece um contrato consolidado para estatísticas e ocupação por slots;
- o overlay precisa montar sua própria leitura mais útil em cima de um modelo que não foi desenhado para isso.
Com a direção nova do usuário, há um problema adicional: não basta rebaixar bytes a papel secundário no contrato exposto. As estruturas atuais que orbitam essa semântica (`BankPolicy` e `BankStats`) passam a ser vistas como parte do problema e não como base aceitável para a solução.
## Pontos Criticos
- **Fato:** O hardware já é organizado por slots para glyph e sound banks.
- **Fato:** O overlay quer mostrar ocupação por slots, não capacidade em bytes.
- **Fato:** O usuário quer que o contrato exposto use apenas `used_slots` e `total_slots`.
- **Fato:** `BankPolicy` e `BankStats` não devem permanecer como contrato nem como modelagem principal deste domínio.
- **Risco:** Remover essas estruturas sem separar claramente contrato exposto e necessidades internas pode quebrar telemetria e certificação existentes.
- **Risco:** Se bytes continuarem aparecendo no contrato público, a refatoração perde seu objetivo.
- **Tradeoff:** Um contrato mínimo de slots simplifica host/overlay e o domínio exposto, mas exige reposicionar qualquer necessidade residual baseada em bytes.
## Opcoes
- **Opção A (Recomendada):** Introduzir um contrato genérico de memory bank orientado exclusivamente a slots no contrato exposto.
- `MemoryBanks` passa a oferecer um contrato explícito para:
- quantidade de slots;
- slots ocupados;
- consulta de slots;
- enumeração genérica de banks.
- `GLYPH` e `SOUND` tornam-se instâncias desse modelo.
- `BankPolicy` e `BankStats` deixam de existir como superfícies do contrato.
- **Opção B:** Manter `BankPolicy` e `BankStats` internamente, escondendo-os só no host.
- Menor custo imediato.
- Não atende a direção explícita da discussão atual.
- **Opção C:** Preservar um contrato híbrido com slots e bytes lado a lado.
- Dá continuidade incremental.
- Mantém exatamente a ambiguidade que o usuário quer remover.
## Sugestao / Recomendacao
Seguir com a **Opção A**, com os seguintes princípios:
1. O domínio de memory banks deve ser **slot-first**.
2. O contrato exposto deve usar somente `used_slots` e `total_slots`.
3. `BankPolicy` e `BankStats` devem ser removidos por completo.
4. `MemoryBanks` deve possuir um contrato específico e explícito para ocupação por slots.
5. O host overlay deve consumir esse modelo genérico sem saber detalhes especiais de `GLYPH` vs `SOUND`, além de rótulo e contagem.
6. A revisão deve evitar abstração vazia: o contrato genérico precisa mapear diretamente para `GlyphBank` e `SoundBank`.
Nomenclatura canônica acordada para a camada genérica:
- `GLYPH`
- `SOUND`
`GFX` e `AUD` não devem ser usados como nomes canônicos do contrato genérico de banks, pois são apelidos de apresentação e não os nomes corretos do domínio.
## Perguntas em Aberto
- Nenhuma resposta final ainda sobre a forma exata do artefato, mas em 2026-04-10 o usuário fechou os seguintes direcionadores:
- a telemetria necessária deve ser gerenciada pelo `AssetManager`, adicionando os banks ao payload;
- a telemetria deve carregar somente o enum do tipo do bank, não uma abstração genérica adicional no contrato;
- o detalhamento operacional deve ocorrer por enum de slot;
- exemplos concretos do formato esperado ainda precisam ser avaliados antes de encerrar a agenda.
### Respostas consolidadas desta rodada
1. **Origem da telemetria:** não mover a genericidade principal para `MemoryBanks`; o `AssetManager` deve gerenciar e expor a telemetria necessária dos banks.
2. **Forma da telemetria:** a telemetria exposta deve carregar somente o enum do tipo do bank.
3. **Detalhamento dos slots:** a leitura operacional deve ser feita por enum de slot.
4. **Formato preferido:** seguir com um resumo por bank no formato do exemplo 1 (`bank_type`, `used_slots`, `total_slots`).
5. **Bytes fake:** bytes não devem continuar no contrato novo de telemetria dos banks.
6. **Certificação:** as regras `max_gfx_bytes` e `max_audio_bytes` devem sair e ser substituídas por limites de slots para `GLYPH` e `SOUND`.
7. **Origem do contrato visível:** o `AssetManager` deve expor diretamente esse resumo por bank.
Exemplo alvo discutido:
```rust
pub struct BankTelemetry {
pub bank_type: BankType,
pub used_slots: usize,
pub total_slots: usize,
}
```
Origem esperada:
```rust
impl AssetManager {
pub fn bank_telemetry(&self) -> Vec<BankTelemetry> { ... }
}
```
Impacto já identificado para certificação:
- remover `max_gfx_bytes`
- remover `max_audio_bytes`
- substituir por algo como:
- `max_glyph_slots_used`
- `max_sound_slots_used`
## Criterio para Encerrar
Esta agenda pode ser encerrada quando houver direção fechada sobre:
- contrato genérico por slots;
- remoção completa de `BankPolicy` e `BankStats`;
- ponto de residência da abstração (`MemoryBanks`, HAL, ou ambos);
- impacto esperado em overlay, telemetria e `AssetManager`.
*(Critérios atingidos em 2026-04-10)*