prometeu-runtime/docs/runtime/pull-requests/013-tile-bank-runtime-contract-alignment.md

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