align packer specs and loader

docs/runtime/agendas/README.md

@@ -24,6 +24,7 @@ As agendas atuais são:
 - `020-perf-host-debug-overlay-isolation.md`
 - `021-perf-vm-allocation-and-copy-pressure.md`
 - `022-perf-cartridge-boot-and-program-ownership.md`
+- `023-asset-codec-none-vs-raw.md`
 ## Sequenciamento Recomendado [PERF]
 
 Ordem sugerida para discussao das agendas de performance:

docs/runtime/learn/mental-model-asset-management.md

@@ -5,6 +5,7 @@ Companion specs:
 
 - [`../specs/13-cartridge.md`](../specs/13-cartridge.md)
 - [`../specs/15-asset-management.md`](../specs/15-asset-management.md)
+- [`../specs/04-gfx-peripheral.md`](../specs/04-gfx-peripheral.md)
 
 Origin decision: [`../decisions/011-assets-pa-autocontained-runtime-contract.md`](../decisions/011-assets-pa-autocontained-runtime-contract.md)
 
@@ -104,6 +105,36 @@ The key point is to separate:
 - the asset storage contract;
 - the operational strategy for reading and decode.
 
+## Serialized Form Is Not Resident Form
+
+One of the most important asset-management lessons in the current runtime is that `RAW` does not mean "bitwise identical to in-memory layout".
+
+The tile-bank path is the concrete example:
+
+- the serialized payload stores indexed pixels as packed `4bpp`;
+- the palette table remains serialized as `RGB565` little-endian;
+- the runtime expands pixels into one `u8` index per pixel after decode.
+
+That is why `AssetEntry.size` and `AssetEntry.decoded_size` must be thought of as different concepts:
+
+- `size` is transport cost inside `assets.pa`;
+- `decoded_size` is resident-bank cost after materialization.
+
+If those two numbers are treated as interchangeable, telemetry, budgets, and validation all become misleading.
+
+## Tile Banks Teach The Real Boundary
+
+Tile banks are useful because they show the real separation of concerns:
+
+- `assets.pa` defines the serialized envelope and metadata needed to reconstruct the bank;
+- the runtime validates that metadata against the expected v1 contract;
+- the resident `TileBank` is a runtime object, not a direct view over the cold bytes.
+
+This is the right PROMETEU mental model:
+
+- cartridge asset bytes are transport;
+- bank objects are execution state.
+
 ## Why This Fits PROMETEU
 
 This model fits the project well because:

docs/runtime/learn/mental-model-gfx.md

@@ -3,6 +3,8 @@
 Status: pedagogical
 Companion spec: [`../specs/04-gfx-peripheral.md`](../specs/04-gfx-peripheral.md)
 
+Related asset spec: [`../specs/15-asset-management.md`](../specs/15-asset-management.md)
+
 PROMETEU treats graphics as an explicit peripheral, not as a modern GPU.
 
 The right mental model is a retro 2D machine with:
@@ -10,7 +12,7 @@ The right mental model is a retro 2D machine with:
 - framebuffer;
 - tile banks;
 - tile layers;
-- sprites por ordem de desenho;
+- sprites ordered by draw order;
 - deterministic composition per frame.
 
 ## Why This Exists
@@ -57,6 +59,30 @@ That enables:
 - HUD themes;
 - day and night cycles.
 
+In the current tile-bank v1 baseline, this palette model is intentionally bounded:
+
+- each bank carries `64` palettes;
+- each palette carries `16` colors;
+- `palette_id` is therefore a small runtime-facing selector, not an open-ended color namespace.
+
+That limit is not incidental bookkeeping. It is part of how art packaging, runtime validation, and rendering stay aligned.
+
+## Tile Banks Are Decoded Runtime Objects
+
+The most useful intuition is to separate three layers:
+
+- authored indexed art;
+- serialized cart payload;
+- resident runtime bank.
+
+For tile banks in v1:
+
+- authored pixels are logical indices `0..15`;
+- serialized payload stores those indices as packed `4bpp`;
+- runtime memory expands them to one `u8` index per pixel after decode.
+
+So when reading the graphics model, do not imagine the renderer reading packed nibbles directly from cartridge storage. The renderer consumes a decoded `TileBank` object whose memory shape is optimized for runtime lookup, not for transport density.
+
 ## Use Cases
 
 - area transition with `Scene Fade`;

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

@@ -1,87 +0,0 @@
-# 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`

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

@@ -1,76 +0,0 @@
-# 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

docs/runtime/pull-requests/README.md

@@ -41,3 +41,5 @@ Nenhuma PR em aberto no momento.
 ## PRs Finalizadas
 
 - `012-assets-preload-asset-id-propagation.md`: concluída. Propagação de ID-based preload concluída em specs e prometeu-hal.
+- `013-tile-bank-runtime-contract-alignment.md`: concluída. Contrato normativo de `tile bank` v1 alinhado entre `specs/04` e `specs/15`.
+- `014-tile-bank-loader-packed-nibbles-and-palette-boundary.md`: concluída. Loader/runtime atualizado para consumir payload serializado `4bpp` packed com `64` paletas por bank.