codec RAW -> NONE

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.