prometeu-runtime/discussion/workflow/agendas/AGD-0024-generic-memory-bank-slot-contract.md

id	ticket	title	status	created	resolved	decision	tags
AGD-0024	generic-memory-bank-slot-contract	Agenda - Generic Memory Bank Slot Contract	accepted	2026-04-10	2026-04-10	DEC-0012	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 SOUND, 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
• SOUND

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:

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

Origem esperada:

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)