# 013 Tile Bank Runtime Contract Alignment

## Briefing

O runtime hoje tem divergencia entre especificacao e implementacao para `tile bank`.

O objetivo desta PR e fechar o contrato runtime-side que o packer deve atender antes de prosseguir com a materializacao definitiva de `tile bank` em `assets.pa`.

Em especial, o repositorio precisa alinhar:

- representacao serializada de indices de pixel;
- cardinalidade de paletas por bank;
- shape minimo de metadata usado pelo loader;
- e semantica de `codec` / `decoded_size` para `TILES`.

## Decisions de Origem

- `docs/packer/decisions/Pack Wizard Pack Execution Semantics Decision.md`
- discussao em andamento no packer sobre `Tile Bank Packing Materialization`

## Alvo

Alinhar o contrato normativo do runtime para `tile bank` v1 com a direcao:

1. indices serializados como `u4` packed em `assets.pa`;
2. paletas serializadas como `RGB565 (u16 little-endian)`;
3. baseline v1 com `64` paletas por bank;
4. `palette_id` valido em `0..63`;
5. `codec = RAW` para tile bank no primeiro wave;
6. metadata minima suficiente para o loader reconstruir o bank em memoria.

## Escopo

- revisar `docs/runtime/specs/04-gfx-peripheral.md`
- revisar `docs/runtime/specs/15-asset-management.md`
- revisar `docs/runtime/specs/13-cartridge.md` somente se necessario para coerencia de referencia
- explicitar o contrato runtime-facing de tile bank em termos de:
  - layout serializado;
  - layout em memoria;
  - limites de paleta;
  - metadata minima;
  - `decoded_size`

## Fora de Escopo

- implementar codigo do loader ou do driver
- ampliar o numero de paletas para `256`
- definir formatos comprimidos para `tile bank`
- definir `tilemap bank`
- redesenhar o modelo de GFX alem do necessario para coerencia do contrato

## Plano de Execucao

1. Auditar e registrar as divergencias atuais entre `specs/04`, `specs/15` e o codigo runtime.
2. Consolidar um baseline unico para `tile bank` v1:
   - payload serializado com indices `u4` packed
   - paletas `64 * 16 * u16`
   - `palette_id` em `0..63`
3. Explicitar que a representacao em memoria pode continuar expandida para `u8` por pixel mesmo quando a forma serializada usa `u4`.
4. Definir metadata minima obrigatoria em `AssetEntry.metadata` para tiles:
   - `tile_size`
   - `width`
   - `height`
   - `palette_count`
   - outros campos apenas se realmente necessarios para reconstruir o bank
5. Fechar a semantica de `decoded_size` para `tile bank` v1.
6. Revisar exemplos e linguagem normativa para remover contradicoes internas.

## Criterios de Aceite

- `docs/runtime/specs/04-gfx-peripheral.md` nao contradiz mais o limite de paletas efetivo de `tile bank`
- `docs/runtime/specs/04-gfx-peripheral.md` define `4bpp` packed como forma serializada do payload
- `docs/runtime/specs/15-asset-management.md` deixa claro o contrato runtime-facing necessario para reconstruir `TileBank`
- a distincao entre forma serializada e forma em memoria fica explicita
- a semantica de `palette_id` e `decoded_size` fica fechada para `tile bank` v1

## Tests / Validacao

- revisao editorial cruzada entre `specs/04`, `specs/13` e `specs/15`
- checklist de coerencia contra o codigo existente do loader/runtime
- validacao com a agenda/decision do packer para garantir que o contrato e implementavel pelo `assets.pa`

## Riscos

- cristalizar cedo demais um limite de paletas que depois precise ser ampliado
- documentar `decoded_size` de forma utilitaria demais e gerar custo futuro em telemetry/budget
- deixar ambiguo o que pertence ao payload versus o que pertence ao `metadata`