prometeu-runtime/docs/runtime/agendas/023-asset-codec-none-vs-raw.md

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.