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