103 lines
4.3 KiB
Markdown
103 lines
4.3 KiB
Markdown
# Decision 013 - Asset Codec `NONE` vs `RAW`
|
|
|
|
## Status
|
|
|
|
Accepted
|
|
|
|
## Contexto
|
|
|
|
O runtime ja fechou o contrato de `tile bank` v1 com:
|
|
|
|
- layout normativo definido por `bank_type` + metadata do proprio bank;
|
|
- payload serializado que pode diferir da forma residente;
|
|
- decode especifico do bank antes da materializacao em memoria.
|
|
|
|
Mesmo assim, o campo `codec` continua publicado como `RAW` em specs e codigo.
|
|
|
|
Isso gera ambiguidade semantica porque `RAW` pode sugerir:
|
|
|
|
- ausencia de compressao;
|
|
- ou bytes ja prontos para consumo direto.
|
|
|
|
Essa segunda leitura conflita com o modelo que o runtime quer preservar:
|
|
|
|
- layout pertence ao contrato do bank;
|
|
- `codec` deve representar a camada generica de transformacao do payload, sem substituir o contrato especifico de formato/layout de banks especializados.
|
|
|
|
## Decisao
|
|
|
|
O valor canonico para ausencia de codec adicional passa a ser `NONE`.
|
|
|
|
Regras da decisao:
|
|
|
|
1. `codec` passa a significar somente:
|
|
- pipeline generico de transformacao do payload; e/ou
|
|
- transformacao de transporte/materializacao que nao pertence ao contrato especifico de um `bank_type`.
|
|
2. O layout serializado de um asset continua pertencendo ao contrato normativo do `bank_type`, nao ao valor de `codec`.
|
|
3. `TILES` v1 deve migrar de `codec = RAW` para `codec = NONE`.
|
|
4. `SOUNDS` v1 tambem deve migrar de `codec = RAW` para `codec = NONE`, para manter semantica uniforme de assets sem codec adicional.
|
|
5. Durante uma janela curta de transicao, o runtime pode aceitar `RAW` como sinonimo legado de `NONE`.
|
|
6. A especificacao publicada deve tratar `NONE` como valor canonico e `RAW` como legado/deprecated durante a migracao.
|
|
|
|
## Rationale
|
|
|
|
`NONE` comunica melhor a ausencia de codec adicional do que `RAW`.
|
|
|
|
Isso importa porque o runtime ja distingue com clareza:
|
|
|
|
- bytes de transporte em `assets.pa`;
|
|
- decode normativo do bank quando o bank ja define seu proprio formato;
|
|
- objeto residente em memoria.
|
|
|
|
Se `codec` continuar com nome que sugere "dados crus", ele enfraquece exatamente a separacao arquitetural que o modelo de assets quer proteger.
|
|
|
|
Ao mesmo tempo, `codec` nao deve ser reduzido conceitualmente a "compressao apenas".
|
|
|
|
Para banks especializados como `TILES` e `SOUNDS`, o contrato principal de formato/layout ja vive no proprio bank, entao `codec` tende a ficar restrito a uma camada adicional ou mesmo ausente.
|
|
|
|
Para banks mais genericos, como um futuro `BLOB`, `codec` pode desempenhar papel mais abrangente e carregar um pipeline generico de formato + transformacao + compactacao.
|
|
|
|
A opcao por uma compatibilidade curta evita uma segunda troca brusca no ecossistema, mas sem cristalizar dupla semantica por tempo indeterminado.
|
|
|
|
## Invariantes / Contrato
|
|
|
|
- `codec` nao define layout especifico de `bank_type`.
|
|
- `codec` define apenas a camada generica de transformacao aplicavel ao payload.
|
|
- `codec = NONE` significa ausencia de codec generico adicional.
|
|
- `codec = NONE` nao significa ausencia de decode do bank.
|
|
- `bank_type` + metadata normativa continuam definindo o layout serializado e a reconstrucao do asset.
|
|
- `RAW`, quando aceito durante a transicao, deve ser tratado como alias legado de `NONE`, nao como semantica diferente.
|
|
- Novo material normativo nao deve publicar `RAW` como valor canonico.
|
|
|
|
## Impactos
|
|
|
|
- Specs:
|
|
- `docs/runtime/specs/15-asset-management.md` deve trocar o valor canonico para `NONE` e explicitar a semantica de transicao.
|
|
- Runtime:
|
|
- o loader deve aceitar `NONE` como valor principal;
|
|
- durante a migracao, pode aceitar `RAW` como alias legado.
|
|
- Modelo de assets:
|
|
- `codec` continua disponivel para desempenhar papel mais abrangente em banks genericos futuros, como `BLOB`.
|
|
- Packer:
|
|
- deve publicar `NONE` como valor canonico no mesmo ciclo de propagacao.
|
|
- Tooling e fixtures:
|
|
- testes, exemplos e dados sinteticos devem migrar para `NONE`.
|
|
- Learn:
|
|
- guias pedagogicos devem refletir que `codec` pertence ao eixo de compressao/transporte, nao ao layout do bank.
|
|
|
|
## Referencias
|
|
|
|
- `docs/runtime/specs/15-asset-management.md`
|
|
- `docs/runtime/specs/04-gfx-peripheral.md`
|
|
- agenda source: `023-asset-codec-none-vs-raw`
|
|
|
|
## Propagacao Necessaria
|
|
|
|
1. Abrir PR de propagacao para:
|
|
- specs;
|
|
- runtime;
|
|
- testes/fixtures;
|
|
- packer.
|
|
2. Publicar `NONE` como canonico e marcar `RAW` como legado durante a janela curta de transicao.
|
|
3. Encerrar a compatibilidade com `RAW` apos a migracao coordenada do runtime e do packer.
|