prometeu-runtime/docs/runtime/pull-requests/015-asset-codec-none-canonicalization-in-specs.md

015 Asset Codec NONE Canonicalization in Specs

Briefing

A decision 013 fechou que o valor canonico para ausencia de codec adicional passa a ser NONE, com RAW tratado apenas como alias legado durante a migracao curta.

O runtime precisa publicar essa semantica nas specs antes de seguir com a propagacao completa em codigo e tooling.

Decisions de Origem

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

Alvo

Atualizar o contrato normativo de assets para que:

1. codec = NONE seja o valor canonico publicado;
2. RAW apareca apenas como legado/deprecated durante a janela curta de transicao;
3. a semantica de codec fique clara como camada generica de transformacao do payload;
4. a diferenca entre codec e layout especifico de bank_type fique explicita.

Escopo

• revisar docs/runtime/specs/15-asset-management.md
• revisar docs/runtime/specs/13-cartridge.md somente se necessario para coerencia de referencia
• revisar docs/runtime/learn/mental-model-asset-management.md somente se a explicacao pedagogica ficar contraditoria apos a mudanca normativa

Fora de Escopo

• alterar codigo do runtime
• alterar packer
• encerrar a compatibilidade legacy em runtime
• redefinir layout de TILES ou SOUNDS

Plano de Execucao

1. Trocar o valor canonico publicado de RAW para NONE em specs/15.
2. Explicitar que:
   • NONE significa ausencia de codec generico adicional;
   • NONE nao significa ausencia de decode do bank;
   • layouts especificos continuam pertencendo ao contrato do bank_type.
3. Registrar RAW apenas como alias legado durante a migracao curta.
4. Revisar linguagem de OP_MODE para evitar que codec pareca dono do layout de TILES.
5. Ajustar referencias editoriais relacionadas se houver contradicao residual.

Criterios de Aceite

• docs/runtime/specs/15-asset-management.md publica NONE como valor canonico
• a spec deixa claro que codec e camada generica de transformacao
• a spec nao atribui a codec o layout especifico de TILES ou SOUNDS
• RAW aparece apenas como legado/deprecated, se aparecer

Tests / Validacao

• revisao editorial cruzada entre specs/15, specs/13 e a decision 013
• checklist de coerencia contra o contrato atual de TILES
• verificacao de que o texto nao fecha prematuramente contratos para banks genericos futuros como BLOB

Riscos

• deixar a linguagem de transicao ambigua e publicar dupla semantica por tempo demais
• descrever NONE de forma que pareca "sem decode"
• endurecer demais codec e bloquear banks genericos futuros