---
id: AGD-0024
ticket: generic-memory-bank-slot-contract
title: Agenda - Generic Memory Bank Slot Contract
status: accepted
created: 2026-04-10
resolved: 2026-04-10
decision: DEC-0012
tags: [runtime, asset, memory-bank, slots, host]
---

# Agenda - Generic Memory Bank Slot Contract

## Contexto

Hoje o runtime e o host expõem bancos de memória principalmente pela ótica de bytes totais/usados, enquanto a organização real do hardware já é fortemente orientada a slots. No estado atual:

- `GFX` e `AUD` aparecem como casos especiais espalhados entre `AssetManager`, `MemoryBanks`, `AssetBridge`, telemetria e overlay;
- os pools concretos são específicos (`glyph_bank_pool`, `sound_bank_pool`);
- a visualização do overlay precisou reinterpretar um modelo em bytes para algo que, operacionalmente, é mais bem entendido como ocupação de slots.

O pedido do usuário é explicitamente mudar essa ênfase: manter bytes como detalhe secundário quando necessário, mas estruturar o modelo principal como **memory banks by slots**, com possibilidade de contrato específico no domínio de `MemoryBanks` para gerir esses valores.

Na continuação da discussão, o usuário endureceu a direção:

- `BankPolicy` deve ser removido por completo;
- `BankStats` deve ser removido por completo;
- o contrato exposto deve trabalhar somente com ocupação por slots, por exemplo:
  - `glyph_slots_occupied / glyph_slots.len()`
  - `sound_slots_occupied / sound_slots.len()`

## Problema

O modelo atual mistura dois níveis de abstração:

1. **Contrato de capacidade em bytes**, útil para certificação e budgets;
2. **Contrato operacional por slots**, que é o que o host e o programador realmente percebem ao lidar com banks.

Isso gera acoplamento e duplicação:

- o domínio conhece `GFX` e `AUD` como exceções, em vez de bancos genéricos com propriedades próprias;
- `BankStats` privilegia bytes e trata slots como apêndice;
- `MemoryBanks` não oferece um contrato consolidado para estatísticas e ocupação por slots;
- o overlay precisa montar sua própria leitura mais útil em cima de um modelo que não foi desenhado para isso.

Com a direção nova do usuário, há um problema adicional: não basta rebaixar bytes a papel secundário no contrato exposto. As estruturas atuais que orbitam essa semântica (`BankPolicy` e `BankStats`) passam a ser vistas como parte do problema e não como base aceitável para a solução.

## Pontos Criticos

- **Fato:** O hardware já é organizado por slots para glyph e sound banks.
- **Fato:** O overlay quer mostrar ocupação por slots, não capacidade em bytes.
- **Fato:** O usuário quer que o contrato exposto use apenas `used_slots` e `total_slots`.
- **Fato:** `BankPolicy` e `BankStats` não devem permanecer como contrato nem como modelagem principal deste domínio.
- **Risco:** Remover essas estruturas sem separar claramente contrato exposto e necessidades internas pode quebrar telemetria e certificação existentes.
- **Risco:** Se bytes continuarem aparecendo no contrato público, a refatoração perde seu objetivo.
- **Tradeoff:** Um contrato mínimo de slots simplifica host/overlay e o domínio exposto, mas exige reposicionar qualquer necessidade residual baseada em bytes.

## Opcoes

- **Opção A (Recomendada):** Introduzir um contrato genérico de memory bank orientado exclusivamente a slots no contrato exposto.
  - `MemoryBanks` passa a oferecer um contrato explícito para:
    - quantidade de slots;
    - slots ocupados;
    - consulta de slots;
    - enumeração genérica de banks.
  - `GLYPH` e `SOUND` tornam-se instâncias desse modelo.
  - `BankPolicy` e `BankStats` deixam de existir como superfícies do contrato.

- **Opção B:** Manter `BankPolicy` e `BankStats` internamente, escondendo-os só no host.
  - Menor custo imediato.
  - Não atende a direção explícita da discussão atual.

- **Opção C:** Preservar um contrato híbrido com slots e bytes lado a lado.
  - Dá continuidade incremental.
  - Mantém exatamente a ambiguidade que o usuário quer remover.

## Sugestao / Recomendacao

Seguir com a **Opção A**, com os seguintes princípios:

1. O domínio de memory banks deve ser **slot-first**.
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 `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`
- `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.

## Perguntas em Aberto

- Nenhuma resposta final ainda sobre a forma exata do artefato, mas em 2026-04-10 o usuário fechou os seguintes direcionadores:
  - a telemetria necessária deve ser gerenciada pelo `AssetManager`, adicionando os banks ao payload;
  - a telemetria deve carregar somente o enum do tipo do bank, não uma abstração genérica adicional no contrato;
  - o detalhamento operacional deve ocorrer por enum de slot;
  - exemplos concretos do formato esperado ainda precisam ser avaliados antes de encerrar a agenda.

### Respostas consolidadas desta rodada

1. **Origem da telemetria:** não mover a genericidade principal para `MemoryBanks`; o `AssetManager` deve gerenciar e expor a telemetria necessária dos banks.
2. **Forma da telemetria:** a telemetria exposta deve carregar somente o enum do tipo do bank.
3. **Detalhamento dos slots:** a leitura operacional deve ser feita por enum de slot.
4. **Formato preferido:** seguir com um resumo por bank no formato do exemplo 1 (`bank_type`, `used_slots`, `total_slots`).
5. **Bytes fake:** bytes não devem continuar no contrato novo de telemetria dos banks.
6. **Certificação:** as regras `max_gfx_bytes` e `max_audio_bytes` devem sair e ser substituídas por limites de slots para `GLYPH` e `SOUND`.
7. **Origem do contrato visível:** o `AssetManager` deve expor diretamente esse resumo por bank.

Exemplo alvo discutido:

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

Origem esperada:

```rust
impl AssetManager {
    pub fn bank_telemetry(&self) -> Vec<BankTelemetry> { ... }
}
```

Impacto já identificado para certificação:

- remover `max_gfx_bytes`
- remover `max_audio_bytes`
- substituir por algo como:
  - `max_glyph_slots_used`
  - `max_sound_slots_used`

## Criterio para Encerrar

Esta agenda pode ser encerrada quando houver direção fechada sobre:

- contrato genérico por slots;
- remoção completa de `BankPolicy` e `BankStats`;
- ponto de residência da abstração (`MemoryBanks`, HAL, ou ambos);
- impacto esperado em overlay, telemetria e `AssetManager`.
*(Critérios atingidos em 2026-04-10)*