[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
+1 -1
View File
@@ -16,7 +16,7 @@
{"type":"discussion","id":"DSC-0011","status":"open","ticket":"perf-gfx-render-pipeline-and-dirty-regions","title":"Agenda - [PERF] GFX Render Pipeline and Dirty Regions","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0010","file":"workflow/agendas/AGD-0010-perf-gfx-render-pipeline-and-dirty-regions.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0012","status":"open","ticket":"perf-runtime-introspection-syscalls","title":"Agenda - [PERF] Runtime Introspection Syscalls","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0011","file":"workflow/agendas/AGD-0011-perf-runtime-introspection-syscalls.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0013","status":"open","ticket":"perf-host-debug-overlay-isolation","title":"Agenda - [PERF] Host Debug Overlay Isolation","created_at":"2026-03-27","updated_at":"2026-04-10","tags":[],"agendas":[{"id":"AGD-0012","file":"workflow/agendas/AGD-0012-perf-host-debug-overlay-isolation.md","status":"done","created_at":"2026-03-27","updated_at":"2026-04-10"},{"id":"AGD-0022","file":"AGD-0022-host-overlay-tooling-boundary-revision.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"},{"id":"AGD-0023","file":"AGD-0023-overlay-log-metric-last-frame.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"}],"decisions":[{"id":"DEC-0007","file":"workflow/decisions/DEC-0007-perf-host-debug-overlay-isolation.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"},{"id":"DEC-0009","file":"DEC-0009-host-overlay-tooling-boundary.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10","ref_agenda":"AGD-0022"},{"id":"DEC-0010","file":"DEC-0010-overlay-log-metric-last-frame.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10","ref_agenda":"AGD-0023"}],"plans":[{"id":"PLN-0006","file":"workflow/plans/PLN-0006-perf-host-debug-overlay-isolation.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"},{"id":"PLN-0008","file":"PLN-0008-host-overlay-native-composition-alignment.md","status":"in_progress","created_at":"2026-04-10","updated_at":"2026-04-10","ref_decisions":["DEC-0007","DEC-0008","DEC-0009","DEC-0010"]}],"lessons":[{"id":"LSN-0027","file":"lessons/DSC-0013-perf-host-debug-overlay-isolation/LSN-0027-host-debug-overlay-isolation.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
{"type":"discussion","id":"DSC-0024","status":"open","ticket":"generic-memory-bank-slot-contract","title":"Agenda - Generic Memory Bank Slot Contract","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["runtime","asset","memory-bank","slots","host"],"agendas":[{"id":"AGD-0024","file":"AGD-0024-generic-memory-bank-slot-contract.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"}],"decisions":[{"id":"DEC-0012","file":"DEC-0012-asset-manager-bank-telemetry-slot-contract.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10","ref_agenda":"AGD-0024"}],"plans":[{"id":"PLN-0010","file":"PLN-0010-asset-manager-bank-telemetry-slot-contract.md","status":"open","created_at":"2026-04-10","updated_at":"2026-04-10","ref_decisions":["DEC-0012"]}],"lessons":[]}
{"type":"discussion","id":"DSC-0024","status":"open","ticket":"generic-memory-bank-slot-contract","title":"Agenda - Generic Memory Bank Slot Contract","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["runtime","asset","memory-bank","slots","host"],"agendas":[{"id":"AGD-0024","file":"AGD-0024-generic-memory-bank-slot-contract.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"}],"decisions":[{"id":"DEC-0012","file":"DEC-0012-asset-manager-bank-telemetry-slot-contract.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10","ref_agenda":"AGD-0024"}],"plans":[{"id":"PLN-0010","file":"PLN-0010-asset-manager-bank-telemetry-slot-contract.md","status":"in_progress","created_at":"2026-04-10","updated_at":"2026-04-10","ref_decisions":["DEC-0012"]}],"lessons":[]}
{"type":"discussion","id":"DSC-0014","status":"open","ticket":"perf-vm-allocation-and-copy-pressure","title":"Agenda - [PERF] VM Allocation and Copy Pressure","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0013","file":"workflow/agendas/AGD-0013-perf-vm-allocation-and-copy-pressure.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0015","status":"open","ticket":"perf-cartridge-boot-and-program-ownership","title":"Agenda - [PERF] Cartridge Boot and Program Ownership","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0014","file":"workflow/agendas/AGD-0014-perf-cartridge-boot-and-program-ownership.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0016","status":"done","ticket":"tilemap-empty-cell-vs-tile-id-zero","title":"Tilemap Empty Cell vs Tile ID Zero","created_at":"2026-03-27","updated_at":"2026-04-09","tags":[],"agendas":[{"id":"AGD-0015","file":"workflow/agendas/AGD-0015-tilemap-empty-cell-vs-tile-id-zero.md","status":"done","created_at":"2026-03-27","updated_at":"2026-04-09"}],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0022","file":"lessons/DSC-0016-tilemap-empty-cell-semantics/LSN-0022-tilemap-empty-cell-convergence.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]}
@@ -82,13 +82,13 @@ Seguir com a **Opção A**, com os seguintes princípios:
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.
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`
- `SOUND`
- `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.
@@ -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.
@@ -2,152 +2,193 @@
id: PLN-0010
ticket: generic-memory-bank-slot-contract
title: PR/Plan - Asset Manager Bank Telemetry Slot Contract
status: open
status: in_progress
created: 2026-04-10
completed:
tags: [runtime, asset, memory-bank, slots, host, telemetry]
tags: [runtime, asset, memory-bank, slots, host, telemetry, certification]
---
## Objective
## Briefing
Implement the `DEC-0012` bank telemetry contract so `AssetManager` exposes slot-based bank summaries using canonical bank names `GLYPH` and `SOUND`, while host overlay and certification consume slot-based limits instead of byte-based bank metrics.
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.
## Background
## Decisions de Origem
`DEC-0012` locked the bank telemetry contract around a simple slot-first structure:
- `DEC-0012` - Asset Manager Bank Telemetry Slot Contract
```rust
pub struct BankTelemetry {
pub bank_type: BankType,
pub used_slots: usize,
pub total_slots: usize,
}
```
## Alvo
This replaces the old bank telemetry path that relied on byte-oriented structures and presentation aliases. The implementation must remove `BankPolicy` and `BankStats` from the exposed bank telemetry contract path, move visible bank summaries to `AssetManager`, and migrate certification rules from byte-based thresholds to slot-based thresholds.
Deliver a canonical bank telemetry path with these properties:
## Scope
- `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 visible slot-based `BankTelemetry` contract owned by `AssetManager`.
- Remove `BankStats` from the public bank telemetry contract path.
- Remove `BankPolicy` from the bank telemetry contract path and refactor internal code accordingly.
- Update bridge/consumer APIs so bank summaries come from `AssetManager` slot telemetry.
- Migrate certification from `max_gfx_bytes` / `max_audio_bytes` to slot-based limits for `GLYPH` and `SOUND`.
- Update host overlay to iterate `AssetManager` bank telemetry using canonical `GLYPH` and `SOUND` labels.
- Update specs/docs affected by the contract change.
### Excluded
- Adding new bank kinds beyond the currently supported `GLYPH` and `SOUND`.
- Reworking unrelated asset load/commit semantics.
- Redesigning generic slot-detail payloads beyond the accepted summary shape unless implementation requires a narrowly scoped helper.
- 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.
## Execution Steps
## Fora de Escopo
### Step 1 - Introduce `BankTelemetry` in the exposed asset contract
- 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 new slot-based summary type and make it the canonical visible representation of bank telemetry.
Define the canonical shared types and trait surface for slot-first bank telemetry.
**How:**
Add `BankTelemetry` to the HAL asset domain and ensure canonical naming uses `GLYPH` and `SOUND`. Remove or deprecate exposed `BankStats` paths that conflict with the new contract.
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`
### Step 2 - Make `AssetManager` expose bank telemetry directly
**Depends on:**
- None
### Step 2 - Refactor AssetManager to produce slot-first summaries
**What:**
Implement `AssetManager` support for returning `Vec<BankTelemetry>` from live slot occupancy.
Move visible bank summary generation to a canonical `AssetManager` slot telemetry path.
**How:**
Compute `used_slots` from current slot occupancy and `total_slots` from the fixed slot arrays for `GLYPH` and `SOUND`. Keep implementation simple and derive the summary directly from the installed slots. Refactor any existing public bank-info consumers away from byte-oriented APIs.
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`
### Step 3 - Remove byte-based bank certification rules
**Depends on:**
- Step 1
### Step 3 - Migrate runtime and host consumers to the new summary
**What:**
Replace byte-based certification limits for banks with slot-based limits.
Replace every bank summary consumer that still expects byte-oriented telemetry.
**How:**
Remove `max_gfx_bytes` and `max_audio_bytes` from certification config and certifier checks. Introduce slot-based limits such as `max_glyph_slots_used` and `max_sound_slots_used`, and evaluate them against `BankTelemetry` summaries or equivalent slot-based data available at frame-end.
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`
### Step 4 - Update host overlay to consume slot telemetry
**Depends on:**
- Step 3
### Step 5 - Remove residual canonical-path names and semantics that conflict with DEC-0012
**What:**
Replace hardcoded bank presentation with iteration over `AssetManager` bank telemetry.
Eliminate remaining visible-path terminology and structures that preserve the old model.
**How:**
Render one bar per bank using `bank_type`, `used_slots`, and `total_slots`. Use canonical labels `GLYPH` and `SOUND`, and remove any byte-based bank presentation from the overlay.
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/host/prometeu-host-desktop-winit/src/overlay.rs`
- Any host-side adapter/helper used to access asset telemetry
### Step 5 - Remove obsolete structures from the contract path
**What:**
Eliminate `BankPolicy` and `BankStats` from the exposed bank telemetry path.
**How:**
Refactor code so the new slot-based path is the only public contract. If internal implementation helpers must remain temporarily during migration, keep them private and make sure no consumer depends on them as contract.
**File(s):**
- `crates/console/prometeu-drivers/src/asset.rs`
- `crates/console/prometeu-hal/src/asset.rs`
- Related callers revealed during implementation
- `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`
### Step 6 - Update normative documentation
**Depends on:**
- Step 4
### Step 6 - Update published specifications
**What:**
Align specifications with the new slot-based bank telemetry contract.
Align canonical docs with the implemented slot-first bank contract.
**How:**
Update relevant runtime documentation to describe bank occupancy in terms of `GLYPH` and `SOUND` slot usage, and remove outdated references to byte-based bank telemetry where they were treated as visible contract.
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/10-debug-inspection-and-profiling.md`
- `docs/specs/runtime/15-asset-management.md`
- Any additional touched runtime spec chapter
- `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
## Test Requirements
**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
- `AssetManager` reports correct `BankTelemetry` for empty and occupied `GLYPH` / `SOUND` slots.
- Certification slot limits trigger correctly for `GLYPH` and `SOUND`.
- Overlay rendering accepts generic bank telemetry iteration.
- 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
- `cargo check` for affected HAL, drivers, system, and host crates.
- Focused tests for asset bank telemetry and certification migration.
- 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
- Run the desktop host and confirm banks appear as `GLYPH` and `SOUND`.
- Confirm bank bars track occupied slots instead of bytes.
- Confirm certification behavior still reports bank pressure using slot limits.
## Acceptance Criteria
- [ ] `AssetManager` exposes a visible `BankTelemetry` summary with `bank_type`, `used_slots`, and `total_slots`.
- [ ] Canonical bank names in the new contract are `GLYPH` and `SOUND`.
- [ ] Byte-based bank certification limits are removed and replaced by slot-based limits.
- [ ] Host overlay renders bank occupancy from generic slot telemetry rather than byte-oriented hardcoded bank logic.
- [ ] `BankPolicy` and `BankStats` are no longer part of the exposed bank telemetry contract path.
- 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` accepted and unchanged.
- `DEC-0012` remains accepted and unchanged.
- Existing `BankType` enum values remain `GLYPH` and `SOUNDS`.
- `AssetManager` remains the asset-domain owner for slot occupancy summaries.
## Risks
## Riscos
- Removing byte-based bank paths may have wider ripple effects than expected if old APIs are reused outside the overlay.
- The line between “removed from contract path” and “removed completely from implementation” must stay explicit during refactor to avoid accidental partial migration.
- Certification migration must stay synchronized with telemetry migration or the host and certifier will diverge semantically.
- 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.