# 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.