[PERF] Host Debug Overlay Isolation
This commit is contained in:
@@ -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.
|
||||
Reference in New Issue
Block a user