From 147f97c5c4a7f85741a40c2047be9d1afd16740b Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Fri, 20 Mar 2026 07:41:44 +0000 Subject: [PATCH] align packer specs and loader --- ...13-tile-bank-runtime-contract-alignment.md | 87 +++++++++++++++++++ ...der-packed-nibbles-and-palette-boundary.md | 76 ++++++++++++++++ 2 files changed, 163 insertions(+) create mode 100644 docs/runtime/pull-requests/013-tile-bank-runtime-contract-alignment.md create mode 100644 docs/runtime/pull-requests/014-tile-bank-loader-packed-nibbles-and-palette-boundary.md diff --git a/docs/runtime/pull-requests/013-tile-bank-runtime-contract-alignment.md b/docs/runtime/pull-requests/013-tile-bank-runtime-contract-alignment.md new file mode 100644 index 00000000..3d2d8fbc --- /dev/null +++ b/docs/runtime/pull-requests/013-tile-bank-runtime-contract-alignment.md @@ -0,0 +1,87 @@ +# 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` diff --git a/docs/runtime/pull-requests/014-tile-bank-loader-packed-nibbles-and-palette-boundary.md b/docs/runtime/pull-requests/014-tile-bank-loader-packed-nibbles-and-palette-boundary.md new file mode 100644 index 00000000..b10b7714 --- /dev/null +++ b/docs/runtime/pull-requests/014-tile-bank-loader-packed-nibbles-and-palette-boundary.md @@ -0,0 +1,76 @@ +# 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` 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`. +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` 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