79 lines
3.9 KiB
Markdown
79 lines
3.9 KiB
Markdown
---
|
|
id: DEC-0012
|
|
ticket: generic-memory-bank-slot-contract
|
|
title: Decision - Asset Manager Bank Telemetry Slot Contract
|
|
status: accepted
|
|
created: 2026-04-10
|
|
updated: 2026-04-10
|
|
agenda: AGD-0024
|
|
tags: [runtime, asset, memory-bank, slots, host, telemetry]
|
|
---
|
|
|
|
# Decision - Asset Manager Bank Telemetry Slot Contract
|
|
|
|
## Status
|
|
**Accepted**
|
|
|
|
## Contexto
|
|
O modelo atual de banks ainda carrega forte semântica orientada a bytes e estruturas antigas como `BankPolicy` e `BankStats`, enquanto o consumo real desejado pelo host e pela inspeção técnica é orientado a slots. Além disso, os bytes historicamente usados nesse caminho foram considerados inadequados para sustentar o novo contrato de telemetria de banks.
|
|
|
|
Durante a discussão, ficou explícito que:
|
|
|
|
- o resumo visível de banks deve ser exposto diretamente pelo `AssetManager`;
|
|
- a telemetria de banks deve usar somente o enum do tipo do bank;
|
|
- a semântica operacional deve ser `used_slots / total_slots`;
|
|
- `GFX` e `AUD` não são nomes canônicos do domínio; os nomes corretos são `GLYPH` e `SOUND`;
|
|
- a certificação de banks deve deixar de usar limites em bytes e passar a usar limites por slots.
|
|
|
|
## Decisao
|
|
1. O contrato visível de telemetria de banks MUST be exposed by `AssetManager`.
|
|
2. O resumo de bank MUST use the following structure shape:
|
|
|
|
```rust
|
|
pub struct BankTelemetry {
|
|
pub bank_type: BankType,
|
|
pub used_slots: usize,
|
|
pub total_slots: usize,
|
|
}
|
|
```
|
|
|
|
3. O `bank_type` MUST use canonical domain names. For the current banks, the canonical names are `GLYPH` and `SOUND`.
|
|
4. O contrato de telemetria de banks MUST be slot-first and MUST NOT depend on byte counts.
|
|
5. `BankPolicy` e `BankStats` MUST be removed completely from the bank telemetry contract path.
|
|
6. O host overlay MUST consume `AssetManager` bank telemetry instead of hardcoded bank-specific logic.
|
|
7. As regras de certificação `max_gfx_bytes` e `max_audio_bytes` MUST be removed.
|
|
8. A certificação de banks MUST migrate to slot-based limits, using canonical bank-specific slot limits such as:
|
|
- `max_glyph_slots_used`
|
|
- `max_sound_slots_used`
|
|
9. Any remaining byte-based accounting MAY survive only as internal implementation detail if strictly necessary, but it MUST NOT remain part of the exposed bank telemetry contract.
|
|
|
|
## Rationale
|
|
- Slots são a unidade operacional correta para entender ocupação de banks.
|
|
- O `AssetManager` já é o lugar que conhece carregamento, commit e ocupação prática dos banks.
|
|
- Remover bytes do contrato elimina uma fonte de telemetria considerada enganosa.
|
|
- `GLYPH` e `SOUND` preservam a linguagem correta do domínio e evitam apelidos frágeis na interface.
|
|
- Certificação por slots mantém coerência entre contrato exposto, overlay e limites técnicos.
|
|
|
|
## Invariantes / Contrato
|
|
- A telemetria de banks exposta ao restante do sistema sai do `AssetManager`.
|
|
- Cada entrada de bank telemetria informa somente tipo do bank, slots usados e slots totais.
|
|
- O contrato canônico usa `GLYPH` e `SOUND`.
|
|
- O overlay não depende de bytes para mostrar ocupação de banks.
|
|
- A certificação de banks não depende de bytes.
|
|
|
|
## Impactos
|
|
- **AssetManager:** precisa expor `Vec<BankTelemetry>` ou equivalente direto.
|
|
- **HAL / Bridges:** precisam alinhar interfaces consumidoras ao contrato slot-first.
|
|
- **Overlay:** deve iterar a telemetria de banks do `AssetManager`.
|
|
- **Certifier:** precisa trocar limites de bytes por limites de slots para banks.
|
|
- **Legado:** `BankPolicy`, `BankStats`, e caminhos ancorados em `max_gfx_bytes` / `max_audio_bytes` precisam ser removidos ou recolocados fora do contrato exposto.
|
|
|
|
## Referencias
|
|
- `AGD-0024`: Generic Memory Bank Slot Contract.
|
|
- `DEC-0010`: Overlay Log Metric Uses Last Completed Frame.
|
|
|
|
## Propagacao Necessaria
|
|
1. Criar plano de execução para refatorar `AssetManager`, HAL, overlay e certificação.
|
|
2. Remover o caminho de telemetria de banks baseado em bytes.
|
|
3. Migrar limites de certificação de banks para slots.
|