diff --git a/docs/runtime/agendas/023-asset-codec-none-vs-raw.md b/docs/runtime/agendas/023-asset-codec-none-vs-raw.md new file mode 100644 index 00000000..6f5cf4db --- /dev/null +++ b/docs/runtime/agendas/023-asset-codec-none-vs-raw.md @@ -0,0 +1,118 @@ +# 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.