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