[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,61 @@
---
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.
@@ -0,0 +1,50 @@
---
id: DEC-0010
ticket: perf-host-debug-overlay-isolation
title: Decision - [PERF] Overlay Log Metric Uses Last Completed Frame
status: accepted
created: 2026-04-10
updated: 2026-04-10
agenda: AGD-0023
tags: [performance, host, telemetry, logs]
---
# Decision - [PERF] Overlay Log Metric Uses Last Completed Frame
## Status
**Accepted**
## Contexto
O campo `LOGS` do overlay técnico do desktop host estava lendo um contador transitório incrementado durante o frame e zerado no fechamento do frame lógico. Como o Host compõe o overlay de forma assíncrona em relação ao loop interno da máquina, esse valor visual tende a aparecer como `0` mesmo sob stress com alta emissão de logs.
## Decisao
1. O valor visual `LOGS` exposto ao overlay MUST represent the number of logs emitted during the last completed logical frame.
2. O contador transitório intra-frame MAY continue to exist for internal collection and frame-end aggregation, but it MUST NOT be exposed diretamente como métrica visual do overlay.
3. O `AtomicTelemetry::snapshot()` MUST expose the persisted last-frame value for `logs_count`.
4. A certificação MUST evaluate log pressure against the persisted last completed frame value, not against a host-timing-dependent transient value.
## Rationale
- O overlay precisa de um valor estável e observável pelo Host.
- O frame fechado é a unidade correta para comparação com outras métricas como ciclos e syscalls.
- A mesma semântica serve tanto para overlay quanto para certificação, evitando ambiguidade.
## Invariantes / Contrato
- `logs_count` em `TelemetryFrame` significa `logs from last completed logical frame`.
- O reset do contador transitório não pode apagar o valor persistido exposto ao Host.
- O overlay não deve depender de timing fino entre renderização do Host e fechamento do frame lógico.
## Impactos
- **HAL:** `AtomicTelemetry` precisa persistir o valor de logs do frame concluído.
- **Runtime:** no fechamento do frame, o valor de logs do frame deve ser copiado antes do reset do contador transitório.
- **Host overlay:** nenhuma mudança conceitual adicional além de passar a receber um valor útil e estável.
- **Specs:** capítulo de debug deve deixar explícita a semântica de `logs_count`.
## Referencias
- `AGD-0023`: [PERF] Overlay Log Metric Must Show Last Frame.
- `DEC-0008`: Full Migration to Atomic Telemetry.
- `DEC-0009`: Host Overlay Tooling Boundary.
## Propagacao Necessaria
1. Atualizar `PLN-0008` para incluir a semântica last-frame de `LOGS`.
2. Ajustar HAL e runtime para persistir `logs_count` ao final do frame.
3. Atualizar a especificação de debug.
@@ -0,0 +1,78 @@
---
id: DEC-0012
ticket: generic-memory-bank-slot-contract
title: Decision - Asset Manager Bank Telemetry Slot Contract
status: accepted
created: 2026-04-10
updated: 2026-04-10
agenda: AGD-0024
tags: [runtime, asset, memory-bank, slots, host, telemetry]
---
# Decision - Asset Manager Bank Telemetry Slot Contract
## Status
**Accepted**
## Contexto
O modelo atual de banks ainda carrega forte semântica orientada a bytes e estruturas antigas como `BankPolicy` e `BankStats`, enquanto o consumo real desejado pelo host e pela inspeção técnica é orientado a slots. Além disso, os bytes historicamente usados nesse caminho foram considerados inadequados para sustentar o novo contrato de telemetria de banks.
Durante a discussão, ficou explícito que:
- o resumo visível de banks deve ser exposto diretamente pelo `AssetManager`;
- a telemetria de banks deve usar somente o enum do tipo do bank;
- a semântica operacional deve ser `used_slots / total_slots`;
- `GFX` e `AUD` não são nomes canônicos do domínio; os nomes corretos são `GLYPH` e `SOUND`;
- a certificação de banks deve deixar de usar limites em bytes e passar a usar limites por slots.
## Decisao
1. O contrato visível de telemetria de banks MUST be exposed by `AssetManager`.
2. O resumo de bank MUST use the following structure shape:
```rust
pub struct BankTelemetry {
pub bank_type: BankType,
pub used_slots: usize,
pub total_slots: usize,
}
```
3. O `bank_type` MUST use canonical domain names. For the current banks, the canonical names are `GLYPH` and `SOUND`.
4. O contrato de telemetria de banks MUST be slot-first and MUST NOT depend on byte counts.
5. `BankPolicy` e `BankStats` MUST be removed completely from the bank telemetry contract path.
6. O host overlay MUST consume `AssetManager` bank telemetry instead of hardcoded bank-specific logic.
7. As regras de certificação `max_gfx_bytes` e `max_audio_bytes` MUST be removed.
8. A certificação de banks MUST migrate to slot-based limits, using canonical bank-specific slot limits such as:
- `max_glyph_slots_used`
- `max_sound_slots_used`
9. Any remaining byte-based accounting MAY survive only as internal implementation detail if strictly necessary, but it MUST NOT remain part of the exposed bank telemetry contract.
## Rationale
- Slots são a unidade operacional correta para entender ocupação de banks.
- O `AssetManager` já é o lugar que conhece carregamento, commit e ocupação prática dos banks.
- Remover bytes do contrato elimina uma fonte de telemetria considerada enganosa.
- `GLYPH` e `SOUND` preservam a linguagem correta do domínio e evitam apelidos frágeis na interface.
- Certificação por slots mantém coerência entre contrato exposto, overlay e limites técnicos.
## Invariantes / Contrato
- A telemetria de banks exposta ao restante do sistema sai do `AssetManager`.
- Cada entrada de bank telemetria informa somente tipo do bank, slots usados e slots totais.
- O contrato canônico usa `GLYPH` e `SOUND`.
- O overlay não depende de bytes para mostrar ocupação de banks.
- A certificação de banks não depende de bytes.
## Impactos
- **AssetManager:** precisa expor `Vec<BankTelemetry>` ou equivalente direto.
- **HAL / Bridges:** precisam alinhar interfaces consumidoras ao contrato slot-first.
- **Overlay:** deve iterar a telemetria de banks do `AssetManager`.
- **Certifier:** precisa trocar limites de bytes por limites de slots para banks.
- **Legado:** `BankPolicy`, `BankStats`, e caminhos ancorados em `max_gfx_bytes` / `max_audio_bytes` precisam ser removidos ou recolocados fora do contrato exposto.
## Referencias
- `AGD-0024`: Generic Memory Bank Slot Contract.
- `DEC-0010`: Overlay Log Metric Uses Last Completed Frame.
## Propagacao Necessaria
1. Criar plano de execução para refatorar `AssetManager`, HAL, overlay e certificação.
2. Remover o caminho de telemetria de banks baseado em bytes.
3. Migrar limites de certificação de banks para slots.