[PERF] Host Debug Overlay Isolation

This commit is contained in:
2026-04-10 19:16:44 +01:00
parent 58a5f9a3a6
commit 4cdfaefda7
17 changed files with 490 additions and 402 deletions
@@ -15,19 +15,22 @@ tags: [runtime, asset, memory-bank, slots, host, telemetry]
**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.
AGD-0024 fechou a mudança do contrato de banks de um modelo orientado a bytes para um modelo orientado a slots. A agenda também fechou que `BankPolicy` e `BankStats` não são base aceitável para a nova superfície visível e que a telemetria operacional consumida por host e overlay deve sair diretamente do `AssetManager`.
Durante a discussão, ficou explícito que:
Os pontos que a agenda resolveu e que esta decisão precisa cristalizar sem ambiguidade são:
- 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.
- o contrato visível é `slot-first`;
- o resumo visível por bank usa apenas `bank_type`, `used_slots` e `total_slots`;
- o detalhamento operacional ocorre por enum de slot;
- `GLYPH` e `SOUNDS` são os nomes canônicos do domínio;
- `GFX` e `AUD` não são nomes canônicos do contrato;
- a certificação deixa de usar bytes e passa a usar limites por slots;
- a genericidade principal do contrato visível não reside em `MemoryBanks`.
## 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:
1. O contrato visível de telemetria de banks MUST ser exposto diretamente por `AssetManager`.
2. O contrato visível de telemetria de banks MUST NOT ter `MemoryBanks` como superfície principal de exposição. `MemoryBanks` MAY manter detalhes internos de suporte, mas o ponto canônico de consumo visível do sistema SHALL ser `AssetManager`.
3. O resumo canônico por bank MUST usar somente os campos `bank_type`, `used_slots` e `total_slots`, no formato:
```rust
pub struct BankTelemetry {
@@ -37,42 +40,53 @@ pub struct BankTelemetry {
}
```
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:
4. O contrato visível de telemetria de banks MUST ser `slot-first` e MUST NOT depender de contagens de bytes.
5. `bank_type` MUST usar nomes canônicos do domínio. Para os banks atuais, os nomes canônicos são `GLYPH` e `SOUNDS`.
6. `GFX` e `AUD` MUST NOT aparecer como nomes canônicos do contrato genérico de banks. Eles MAY existir apenas como rótulos de apresentação, quando estritamente necessário fora do contrato canônico.
7. `BankPolicy` e `BankStats` MUST ser removidos completamente do caminho do contrato visível de telemetria de banks e MUST NOT permanecer como modelagem principal desse domínio exposto.
8. O overlay do host MUST consumir a telemetria exposta por `AssetManager` e MUST NOT manter lógica hardcoded dependente de bancos específicos para calcular ocupação principal.
9. O detalhamento operacional por slot MUST ser definido por enum de slot, e qualquer inspeção detalhada de ocupação SHALL seguir esse modelo, não um detalhamento baseado em bytes.
10. As regras de certificação `max_gfx_bytes` e `max_audio_bytes` MUST ser removidas.
11. A certificação de banks MUST migrar para limites por slots, usando nomes canônicos de bank, tais como:
- `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.
12. Qualquer contabilização residual em bytes MAY sobreviver apenas como detalhe interno de implementação, quando estritamente necessária, e MUST NOT permanecer no contrato visível de telemetria de banks.
## 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.
- Slots são a unidade operacional real percebida por host, overlay e depuração de banks.
- `AssetManager` é o ponto que já conhece a ocupação efetiva dos banks e, portanto, é o lugar correto para expor o resumo visível.
- Remover bytes do contrato visível evita uma telemetria enganosa e elimina a ambiguidade que a agenda abriu para resolver.
- Fixar `GLYPH` e `SOUNDS` como nomes canônicos evita contaminar o contrato com apelidos de apresentação.
- Fixar enum de slot como detalhamento operacional evita reabrir a discussão sob outra forma durante a implementação.
- Migrar certificação para slots mantém o contrato exposto, o overlay e os limites técnicos usando a mesma semântica.
## 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`.
- A telemetria de banks exposta ao restante do sistema sai de `AssetManager`.
- O contrato visível principal não reside em `MemoryBanks`.
- Cada entrada de telemetria de bank informa somente `bank_type`, `used_slots` e `total_slots`.
- O contrato canônico usa `GLYPH` e `SOUNDS`.
- O detalhamento operacional de slots usa enum de slot.
- 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`.
- **AssetManager:** deve expor `Vec<BankTelemetry>` ou equivalente direto como superfície canônica visível.
- **MemoryBanks:** pode continuar como suporte interno, mas não deve concentrar o contrato visível principal de telemetria.
- **HAL / Bridges:** precisam alinhar qualquer interface consumidora ao contrato `slot-first`.
- **Overlay:** deve iterar a telemetria de banks do `AssetManager` e parar de recomputar a ocupação principal a partir de bytes.
- **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.
- **Legado:** `BankPolicy`, `BankStats`, `max_gfx_bytes` e `max_audio_bytes` precisam ser removidos do caminho canônico dessa capacidade.
## 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.
1. O plano de execução deve refatorar `AssetManager`, `MemoryBanks`, HAL/bridges, overlay e certificação sem reabrir a arquitetura base.
2. O caminho de telemetria de banks baseado em bytes deve ser removido do contrato visível.
3. O detalhamento operacional por enum de slot deve ser propagado para os pontos que inspecionam ocupação detalhada.
4. A certificação de banks deve migrar de limites em bytes para limites em slots.
## Revision Log
- 2026-04-10: Initial decision emitted from `AGD-0024`.
- 2026-04-10: Decision tightened to align explicitly with agenda closure on `AssetManager` ownership, slot-enum operational detail, and `MemoryBanks` non-canonical residency.