prometeu-runtime/docs/runtime/decisions/013-asset-codec-none-vs-raw.md

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.