# 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