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

O contrato visível de telemetria de banks MUST ser exposto diretamente por AssetManager.
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.
O resumo canônico por bank MUST usar somente os campos bank_type, used_slots e total_slots, no formato:

pub struct BankTelemetry {
    pub bank_type: BankType,
    pub used_slots: usize,
    pub total_slots: usize,
}

O contrato visível de telemetria de banks MUST ser slot-first e MUST NOT depender de contagens de bytes.
bank_type MUST usar nomes canônicos do domínio. Para os banks atuais, os nomes canônicos são GLYPH e SOUNDS.
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.
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.
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.
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.
As regras de certificação max_gfx_bytes e max_audio_bytes MUST ser removidas.
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

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

O plano de execução deve refatorar AssetManager, MemoryBanks, HAL/bridges, overlay e certificação sem reabrir a arquitetura base.
O caminho de telemetria de banks baseado em bytes deve ser removido do contrato visível.
O detalhamento operacional por enum de slot deve ser propagado para os pontos que inspecionam ocupação detalhada.
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.

5.9 KiB Raw Blame History