prometeu-runtime/docs/runtime/pull-requests/014-tile-bank-loader-packed-nibbles-and-palette-boundary.md

014 Tile Bank Loader Packed Nibbles and Palette Boundary

Briefing

O codigo do runtime hoje ainda decodifica tile bank como:

• 1 byte por pixel indexado;
• 2048 bytes fixos de paleta;
• validacao efetiva de palette_id em 0..63.

Se o contrato v1 sera u4 packed + RGB565 u16, o loader e os pontos de validacao do runtime precisam ser corrigidos antes de seguir com o packer-side materialization.

Decisions de Origem

• 013-tile-bank-runtime-contract-alignment.md
• docs/packer/decisions/Pack Wizard Pack Execution Semantics Decision.md

Alvo

Atualizar o codigo do runtime para consumir tile bank v1 como:

1. indices de pixel u4 packed no payload serializado;
2. paletas RGB565 (u16 little-endian);
3. 64 paletas por bank no primeiro wave;
4. representacao expandida em memoria para Vec<u8> somente apos decode;
5. validacao coerente de palette_id no ABI/runtime.

Escopo

• atualizar decode de tile bank em prometeu-drivers/src/asset.rs
• revisar comentarios e invariantes em prometeu-hal/src/tile_bank.rs
• revisar pontos de validacao e range de palette_id no runtime path
• ajustar testes existentes do runtime que assumem payload u8 por pixel

Fora de Escopo

• introduzir compressao para tile bank
• ampliar palette_count para 256
• mudar o modelo de TileBank para armazenar nibbles packed em memoria
• mudar o contrato de sound bank
• definir ou implementar tilemap bank

Plano de Execucao

1. Alterar o decode do payload de tile bank para calcular o tamanho esperado de indices como (width * height + 1) / 2.
2. Implementar unpack deterministico de nibbles para a representacao em memoria Vec<u8>.
3. Preservar a leitura das paletas como u16 little-endian.
4. Tornar explicita a quantidade de paletas suportadas em v1 no codigo, evitando magic numbers soltos.
5. Revisar comentarios/documentacao inline em TileBank para diferenciar:
   • payload serializado
   • representacao expandida em memoria
6. Ajustar testes para cobrir:
   • unpack correto de nibbles
   • transparencias (0)
   • limites de paleta
   • rejeicao de buffer curto

Criterios de Aceite

• o loader de tile bank nao assume mais 1 byte por pixel no payload serializado
• o runtime reconstrui corretamente pixel_indices: Vec<u8> a partir de nibbles packed
• o bloco de paletas continua sendo lido como RGB565 u16 little-endian
• o range efetivo de palette_id fica coerente com o contrato v1 de 64 paletas
• os testes do runtime cobrem o novo layout e falhas de tamanho insuficiente

Tests / Validacao

• testes unitarios do decode de tile bank
• testes de roundtrip do loader usando payload sintetico
• validacao de compatibilidade com o contrato normativo atualizado em docs/runtime/specs

Riscos

• unpack incorreto de nibbles gerar corrupcao visual silenciosa
• confusao entre decoded_size logico e tamanho serializado do payload
• deixar o codigo parcialmente alinhado com a spec, mas com ranges de ABI ainda antigos ou contraditorios