119 lines
4.2 KiB
Markdown
119 lines
4.2 KiB
Markdown
# Agenda - Asset Codec `NONE` vs `RAW`
|
|
|
|
## Contexto
|
|
|
|
O runtime acabou de fechar o contrato de `tile bank` v1 com:
|
|
|
|
- layout serializado especifico por `bank_type`;
|
|
- metadata normativa do proprio bank;
|
|
- `size` e `decoded_size` distintos;
|
|
- decode runtime-side que pode transformar a forma serializada em forma residente.
|
|
|
|
Nesse contexto, o campo `codec` continua aparecendo como `RAW` em `specs` e em codigo.
|
|
|
|
Ao mesmo tempo, a direcao arquitetural desejada e mais estreita:
|
|
|
|
- `bank_type` + contrato do bank definem formato/layout;
|
|
- `codec` deve representar compressao ou transformacao generica de transporte;
|
|
- layouts especificos de um bank nao devem vazar para o significado de `codec`.
|
|
|
|
## Problema
|
|
|
|
`RAW` hoje comunica mal a intencao do campo `codec`.
|
|
|
|
Para `TILES`, o payload:
|
|
|
|
- nao esta comprimido;
|
|
- mas tambem nao esta em forma residente;
|
|
- e exige decode normativo do bank antes de virar `TileBank`.
|
|
|
|
Com isso, `RAW` pode ser lido de dois jeitos conflitantes:
|
|
|
|
- "sem compressao";
|
|
- "bytes ja estao crus/prontos para consumo".
|
|
|
|
Se o segundo sentido entrar no modelo mental do projeto, o contrato fica confuso exatamente onde queriamos separar:
|
|
|
|
- `codec` como compressao;
|
|
- layout como contrato do bank.
|
|
|
|
## Pontos Criticos
|
|
|
|
- Fato: `TILES` v1 usa payload serializado `4bpp` packed e runtime materializa `u8` por pixel.
|
|
- Fato: `codec` nao deveria descrever esse layout se o layout ja pertence ao contrato do bank.
|
|
- Fato: `RAW` esta publicado em `specs/15`, fixtures de teste e paths de runtime.
|
|
- Risco: manter `RAW` prolonga leitura ambigua de que `codec` descreve mais do que compressao.
|
|
- Risco: trocar para `NONE` sem fechar linguagem normativa pode gerar migracao incompleta entre runtime e packer.
|
|
- Tradeoff: `NONE` e semanticamente mais honesto para "sem codec adicional", mas exige propagacao coordenada.
|
|
- Hipotese: a troca para `NONE` reduz ambiguidade sem exigir redesenho do modelo de assets, desde que a spec explicite que decode especifico do bank continua existindo mesmo com `codec = NONE`.
|
|
|
|
## Opcoes
|
|
|
|
### Opcao 1 - Manter `RAW`
|
|
|
|
Vantagens:
|
|
|
|
- zero churn imediato;
|
|
- preserva compatibilidade literal com fixtures e tooling atuais.
|
|
|
|
Desvantagens:
|
|
|
|
- mantem um nome que sugere semantica mais larga do que compressao;
|
|
- enfraquece a separacao entre `codec` e layout do bank.
|
|
|
|
### Opcao 2 - Trocar `RAW` por `NONE`
|
|
|
|
Vantagens:
|
|
|
|
- alinha o nome do campo com a ideia de "sem codec adicional";
|
|
- deixa mais claro que o decode de `TILES` vem do contrato do bank, nao do `codec`.
|
|
|
|
Desvantagens:
|
|
|
|
- exige propagacao coordenada em specs, runtime, testes e packer;
|
|
- requer cuidado editorial para nao sugerir que `NONE` significa "sem decode".
|
|
|
|
### Opcao 3 - Introduzir dupla compatibilidade temporaria (`RAW` e `NONE`)
|
|
|
|
Vantagens:
|
|
|
|
- reduz atrito de migracao entre runtime e packer;
|
|
- permite transicao progressiva.
|
|
|
|
Desvantagens:
|
|
|
|
- aumenta a superficie normativa e a ambiguidade por mais tempo;
|
|
- piora o contrato justamente quando o objetivo e simplifica-lo.
|
|
|
|
## Sugestao / Recomendacao
|
|
|
|
Recomendacao principal: adotar `codec = NONE` como contrato alvo e aposentar `RAW`.
|
|
|
|
Motivo:
|
|
|
|
- o layout continua sendo definido por `bank_type` e metadata normativa do bank;
|
|
- `codec` fica semanticamente reservado para compressao ou transformacao generica de transporte;
|
|
- `NONE` descreve melhor a ausencia de codec adicional sem negar que o bank ainda tenha seu proprio decode normativo.
|
|
|
|
Recomendacao de propagacao, se a decisao for confirmada:
|
|
|
|
1. atualizar `specs/15` para explicitar que `NONE` significa "no additional transport codec";
|
|
2. atualizar runtime/tests para aceitar `NONE`;
|
|
3. decidir se havera ou nao uma janela curta de compatibilidade com `RAW`;
|
|
4. alinhar packer para publicar `NONE` no mesmo ciclo.
|
|
|
|
## Perguntas em Aberto
|
|
|
|
1. A transicao deve ser atomica ou com compatibilidade curta `RAW` + `NONE`?
|
|
2. `SOUNDS` tambem deve migrar no mesmo passo para manter uniformidade?
|
|
3. Existe algum artefato externo ao runtime atual que ainda dependa literalmente de `RAW`?
|
|
|
|
## Criterio para Encerrar
|
|
|
|
Esta agenda pode virar `decision` quando houver resposta fechada para:
|
|
|
|
- semantica oficial de `codec` no modelo de assets;
|
|
- string canonica publicada (`NONE` ou permanencia de `RAW`);
|
|
- estrategia de compatibilidade da migracao;
|
|
- lista de propagacao minima em `specs`, runtime e packer.
|