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

O contrato visível de telemetria de banks MUST be exposed by AssetManager.
O resumo de bank MUST use the following structure shape:

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

O bank_type MUST use canonical domain names. For the current banks, the canonical names are GLYPH and SOUND.
O contrato de telemetria de banks MUST be slot-first and MUST NOT depend on byte counts.
BankPolicy e BankStats MUST be removed completely from the bank telemetry contract path.
O host overlay MUST consume AssetManager bank telemetry instead of hardcoded bank-specific logic.
As regras de certificação max_gfx_bytes e max_audio_bytes MUST be removed.
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
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

Criar plano de execução para refatorar AssetManager, HAL, overlay e certificação.
Remover o caminho de telemetria de banks baseado em bytes.
Migrar limites de certificação de banks para slots.

3.9 KiB Raw Blame History