[PERF] Host Debug Overlay Isolation
Intrepid/Prometeu/Runtime/pipeline/pr-master There was a failure building this commit
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good

This commit is contained in:
2026-04-10 19:22:52 +01:00
parent 5436c54e6d
commit 7a696623b5
7 changed files with 98 additions and 436 deletions
@@ -1,147 +0,0 @@
---
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 `SOUNDS`, 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`
- `SOUNDS`
`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)*
@@ -1,92 +0,0 @@
---
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
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`.
Os pontos que a agenda resolveu e que esta decisão precisa cristalizar sem ambiguidade são:
- 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 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 {
pub bank_type: BankType,
pub used_slots: usize,
pub total_slots: usize,
}
```
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`
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 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 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:** 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`, `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. 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.
@@ -1,194 +0,0 @@
---
id: PLN-0010
ticket: generic-memory-bank-slot-contract
title: PR/Plan - Asset Manager Bank Telemetry Slot Contract
status: in_progress
created: 2026-04-10
completed:
tags: [runtime, asset, memory-bank, slots, host, telemetry, certification]
---
## Briefing
Implement `DEC-0012` by replacing the current byte-oriented bank telemetry path with a slot-first contract exposed directly by `AssetManager`. The execution MUST remove `BankPolicy` and `BankStats` from the visible telemetry path, keep canonical bank names aligned with `BankType` (`GLYPH`, `SOUNDS`), make the host overlay consume the new `AssetManager` summary, and migrate bank certification from byte limits to slot limits.
## Decisions de Origem
- `DEC-0012` - Asset Manager Bank Telemetry Slot Contract
## Alvo
Deliver a canonical bank telemetry path with these properties:
- `AssetManager` exposes the visible per-bank summary.
- The visible summary shape is slot-first and limited to `bank_type`, `used_slots`, and `total_slots`.
- Detailed inspection remains slot-based through `SlotRef` / slot enums, not byte-based accounting.
- Host overlay and certification consume the new model.
- Legacy byte-oriented bank telemetry fields and limits are removed from the canonical path.
## Escopo
### Included
- Add a canonical `BankTelemetry` type to the shared HAL asset contract.
- Add an `AssetBridge` method for bank telemetry summaries exposed by `AssetManager`.
- Refactor `AssetManager` in `crates/console/prometeu-drivers` to compute slot-first bank telemetry.
- Remove `BankStats` from the visible bank telemetry path and stop using it for overlay and certification.
- Remove `BankPolicy` as the main modeling surface used to describe visible bank telemetry.
- Keep detailed slot inspection on explicit slot references instead of bank byte summaries.
- Update runtime telemetry / certification to track `max_glyph_slots_used` and `max_sound_slots_used`.
- Update host overlay consumers to render bank occupancy from the new `AssetManager` summary.
- Update runtime specs so the published contract describes slot-first bank telemetry and slot-based certification.
## Fora de Escopo
- Reopening the base architectural decision about whether the visible summary belongs in `AssetManager`.
- Introducing new bank categories beyond the current `GLYPH` and `SOUNDS`.
- Reworking unrelated asset loading semantics, cartridge payload layout, or host UI design beyond adapting bank telemetry consumption.
- Removing all internal byte accounting if some private implementation detail still needs it temporarily.
## Plano de Execucao
### Step 1 - Lock the shared contract in HAL
**What:**
Define the canonical shared types and trait surface for slot-first bank telemetry.
**How:**
Add `BankTelemetry` to `crates/console/prometeu-hal/src/asset.rs` using `bank_type`, `used_slots`, and `total_slots`. Update `crates/console/prometeu-hal/src/asset_bridge.rs` so the visible bridge exposes a bank telemetry summary method from `AssetManager`. Remove or deprecate `BankStats` from the visible bridge path so downstream callers stop depending on byte-oriented bank summaries.
**File(s):**
- `crates/console/prometeu-hal/src/asset.rs`
- `crates/console/prometeu-hal/src/asset_bridge.rs`
**Depends on:**
- None
### Step 2 - Refactor AssetManager to produce slot-first summaries
**What:**
Move visible bank summary generation to a canonical `AssetManager` slot telemetry path.
**How:**
Replace `bank_info(BankType) -> BankStats` with a summary path that reports only slot occupancy for each canonical bank type. Compute `used_slots` from the slot arrays already owned by `AssetManager` (`gfx_slots`, `sound_slots`) or equivalent canonical occupancy state. Keep detailed per-slot inspection in `slot_info(SlotRef)`. Remove `BankPolicy` and its byte counters as the visible modeling surface for bank telemetry; if any internal storage helper remains temporarily, it must not leak into the shared contract.
**File(s):**
- `crates/console/prometeu-drivers/src/asset.rs`
- `crates/console/prometeu-drivers/src/memory_banks.rs`
**Depends on:**
- Step 1
### Step 3 - Migrate runtime and host consumers to the new summary
**What:**
Replace every bank summary consumer that still expects byte-oriented telemetry.
**How:**
Update runtime and host callers to consume `BankTelemetry` from `AssetManager` instead of `BankStats`. Replace any direct `bank_info(BankType)` callsites with the new canonical summary path. Preserve slot-level inspection through `slot_info(SlotRef)` where detailed occupancy is needed. The host overlay must render bank occupancy from the `AssetManager` summary and must not reconstruct primary bank occupancy from bytes.
**File(s):**
- `crates/console/prometeu-system/src/virtual_machine_runtime/tick.rs`
- `crates/host/prometeu-host-desktop-winit/src/overlay.rs`
- Any additional callsites found through `rg 'bank_info|BankStats' crates`
**Depends on:**
- Step 2
### Step 4 - Replace certification byte limits with slot limits
**What:**
Move bank certification from byte ceilings to slot ceilings.
**How:**
Replace `max_gfx_bytes` and `max_audio_bytes` in telemetry / certification configuration and evaluation with slot-based limits such as `max_glyph_slots_used` and `max_sound_slots_used`. Update runtime accounting to record the maximum occupied slot count per bank during execution. Remove byte-limit evaluation from the bank certification path.
**File(s):**
- `crates/console/prometeu-hal/src/telemetry.rs`
- `crates/console/prometeu-system/src/virtual_machine_runtime/tick.rs`
**Depends on:**
- Step 3
### Step 5 - Remove residual canonical-path names and semantics that conflict with DEC-0012
**What:**
Eliminate remaining visible-path terminology and structures that preserve the old model.
**How:**
Ensure no visible bank telemetry path still uses `GFX` / `AUD` as canonical names, `BankStats` as the summary type, or byte fields as the public bank occupancy contract. Keep `GLYPH` and `SOUNDS` aligned with the existing `BankType` enum. If bridges, docs, or helper APIs still expose the old path, remove or rename them in the same change set so the canonical path is unambiguous.
**File(s):**
- `crates/console/prometeu-hal/src/asset.rs`
- `crates/console/prometeu-hal/src/asset_bridge.rs`
- `crates/console/prometeu-drivers/src/asset.rs`
- `crates/console/prometeu-system/src/virtual_machine_runtime/tick.rs`
- `crates/host/prometeu-host-desktop-winit/src/overlay.rs`
**Depends on:**
- Step 4
### Step 6 - Update published specifications
**What:**
Align canonical docs with the implemented slot-first bank contract.
**How:**
Update runtime specs to state that bank telemetry is exposed from `AssetManager`, that the published per-bank summary is slot-first, that detailed occupancy inspection remains slot-based, and that certification uses slot ceilings instead of byte ceilings. Remove residual published references to `max_gfx_bytes`, `max_audio_bytes`, or byte-oriented bank summaries in canonical specs.
**File(s):**
- `docs/specs/runtime/15-asset-management.md`
- `docs/specs/runtime/10-debug-inspection-and-profiling.md`
- Any additional runtime spec file that still documents byte-based bank certification or overlay bank summary consumption
**Depends on:**
- Step 5
## Criterios de Aceite
- [ ] `AssetManager` is the canonical visible source of bank telemetry.
- [ ] The visible bank summary contract uses only `bank_type`, `used_slots`, and `total_slots`.
- [ ] Canonical bank names in the visible contract are `GLYPH` and `SOUNDS`.
- [ ] `BankStats` is no longer used as the visible bank telemetry summary type.
- [ ] `BankPolicy` is not the main visible modeling surface for bank telemetry.
- [ ] Host overlay bank occupancy uses the new `AssetManager` bank summary.
- [ ] Detailed occupancy inspection remains slot-based via slot references or equivalent slot enums.
- [ ] `max_gfx_bytes` and `max_audio_bytes` are removed from bank certification.
- [ ] Slot-based bank certification limits exist and are enforced.
- [ ] Published runtime specs describe the slot-first contract and slot-based certification model.
## Tests / Validacao
### Unit Tests
- Add or update tests in `crates/console/prometeu-drivers/src/asset.rs` to verify the bank summary reports correct `used_slots` and `total_slots` for `GLYPH` and `SOUNDS`.
- Add or update tests in `crates/console/prometeu-hal/src/telemetry.rs` to verify slot-based certification thresholds trigger correctly and byte-based limits no longer exist in the bank path.
- Keep slot inspection tests proving `slot_info(SlotRef)` remains the detailed inspection mechanism.
### Integration Tests
- Run `cargo test -p prometeu-drivers`.
- Run `cargo test -p prometeu-hal`.
- Run `cargo test -p prometeu-system`.
- Run `cargo test -p prometeu-host-desktop-winit` if overlay bank telemetry callsites are changed there.
- Run `cargo check` for the full touched workspace if cross-crate API changes make targeted tests insufficient.
### Manual Verification
- Start the desktop host and confirm the overlay shows per-bank occupancy using slot counts, not bytes.
- Confirm the overlay labels use `GLYPH` and `SOUNDS` or approved presentation labels derived from those canonical bank types.
- Confirm certification output reports slot-limit violations and no longer reports `max_gfx_bytes` / `max_audio_bytes`.
- Confirm detailed slot inspection still works for both glyph and sound slots.
## Dependencies
- `DEC-0012` remains accepted and unchanged.
- Existing `BankType` enum values remain `GLYPH` and `SOUNDS`.
- `AssetManager` remains the asset-domain owner for slot occupancy summaries.
## Riscos
- Cross-crate trait changes in `AssetBridge` may create a wider refactor than the bank telemetry callsites initially suggest.
- Removing `BankStats` from the visible path may expose hidden byte-based assumptions in runtime telemetry, overlay formatting, or tests.
- Certification migration may fail partially if slot maxima are recorded in one layer while enforcement still reads old byte fields in another layer.
- If byte accounting is still needed internally during the refactor, the implementation can accidentally leak that detail back into public interfaces unless the change set is kept cohesive.