prometeu-runtime/discussion/workflow/decisions/DEC-0012-asset-manager-bank-telemetry-slot-contract.md

---
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.