align packer specs and loader
This commit is contained in:
parent
03494c8cd7
commit
147f97c5c4
SSH Key Fingerprint:
SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
@ -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`
|
||||
@ -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<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
|
||||
Loading…
x
Reference in New Issue
Block a user