prometeu-runtime/discussion/workflow/decisions/DEC-0005-asset-entry-codec-enum-contract.md

id	ticket	title	status	created	accepted	agenda	plans	tags
DEC-0005	asset-entry-codec-enum-with-metadata	Asset Entry Codec Enum Contract	accepted	2026-04-09	2026-04-09	AGD-0019	PLN-0004	asset runtime codec metadata

Status

Accepted on 2026-04-09.

Contexto

A discussao AGD-0019 fechou que o campo codec de AssetEntry faz parte do contrato de dominio do runtime e nao deve permanecer como texto frouxo consumido ad hoc por loaders.

Hoje o empacotamento e produzido no Studio em Java/Jackson e o runtime consome o header JSON de asset.pa em Rust. Portanto, o contrato precisa distinguir claramente:

• o wire format serializado pelo Studio;
• o modelo tipado carregado pelo runtime;
• a relacao entre o discriminante do codec e qualquer metadata especifica de codec.

A decisao tambem precisa consolidar o fim do alias legado RAW e a politica de falha para codecs desconhecidos.

Decisao

1. AssetEntry.codec no runtime MUST ser representado por um enum tipado, e MUST NOT permanecer como String no modelo carregado.
2. O JSON serializado em asset.pa MUST continuar representando codec como uma string.
3. O runtime Rust MUST desserializar essa string diretamente para o enum de codec no proprio AssetEntry.
4. O spelling textual do codec no JSON MUST seguir exatamente o canon definido por este contrato. O canon inicial MUST ser SCREAMING_SNAKE_CASE, alinhado ao padrao ja usado por BankType. O Studio/paker MUST emitir exatamente esse spelling e MUST NOT introduzir aliases livres.
5. A variante inicial unica do enum MUST ser None.
6. O alias/conceito Raw MUST be removed from the contract and MUST NOT be emitted pelo Studio nem aceito como shape valido futuro.
7. Se o runtime encontrar um codec desconhecido para aquele binario, a validacao de AssetEntry MUST falhar antes de qualquer carga efetiva do asset, e o cartucho MUST ser rejeitado.
8. pipeline MUST NOT fazer parte do modelo operacional do runtime para esse contrato e MAY ser descartado completamente no lado do runtime.
9. Metadados especificos de codec, quando existirem, MUST ser interpretados a partir do codec resolvido e MUST permanecer separados da metadata editorial ou da metadata propria do banco consumidor.
10. A estrategia para o primeiro codec com payload adicional is deferred. Esta decisao fecha apenas o contrato atual e o ponto de extensao, sem antecipar um shape normativo para codecs futuros com payload.

Rationale

• O wire format em string preserva simplicidade e compatibilidade com o Studio em Java/Jackson.
• O enum no runtime torna o contrato exaustivo, evita parsing textual espalhado e reduz drift entre loader, validacao e consumidores.
• Rejeitar codec desconhecido cedo mantem o sistema fail-fast e evita estados parcialmente carregados.
• Remover Raw evita manter semantica historica ambigua em paralelo ao contrato novo.
• Expulsar pipeline do runtime reduz ruido conceitual e impede sobreposicao de responsabilidade com codec.
• Adiar o desenho de codecs com payload evita overdesign antes de existir um caso concreto.

Invariantes / Contrato

• O valor de codec no JSON de asset.pa e um discriminante textual canonico.
• O discriminante textual canonico de codec no JSON usa SCREAMING_SNAKE_CASE.
• O valor de codec carregado em Rust e um enum fechado para o conjunto de codecs suportados por aquele runtime.
• O Studio e o runtime compartilham o mesmo spelling canonico para cada variante.
• O runtime nao oferece modo tolerante para codecs desconhecidos.
• O contrato inicial possui uma unica variante valida: None.
• Raw nao pertence mais ao contrato canonico.
• pipeline nao participa do contrato operacional do runtime.
• Quando metadata.codec existir para algum codec futuro, sua interpretacao dependera do discriminante ja validado.

Impactos

• prometeu-hal deve trocar AssetEntry.codec: String por um enum serializavel/desserializavel com canon textual explicito.
• prometeu-drivers deve remover a aceitacao de RAW como alias legado e passar a operar sobre enum, nao sobre comparacao textual solta.
• O loader/validacao do cart deve falhar cedo se a desserializacao ou validacao do codec falhar.
• O Studio/paker deve emitir exatamente o nome canonico definido para o codec.
• O nome canonico inicial de None no JSON deve ser NONE.
• Nao ha necessidade de definir agora um DTO separado apenas para codec; o proprio AssetEntry continua sendo o contrato serializado e desserializado.

Referencias

• AGD-0019: Asset Entry Codec as Enum with Metadata
• DSC-0017: Asset Entry Metadata Normalization Contract
• LSN-0023: Typed Helpers for Asset Metadata
• crates/console/prometeu-hal/src/asset.rs
• crates/console/prometeu-hal/src/cartridge_loader.rs
• crates/console/prometeu-drivers/src/asset.rs

Propagacao Necessaria

• Atualizar o modelo Rust de AssetEntry para usar enum de codec.
• Atualizar a validacao/desserializacao do header de asset.pa.
• Atualizar drivers para abandonar RAW e comparacoes por String.
• Ajustar o Studio/paker para emitir o spelling canonico escolhido pelo contrato.
• Escrever um plano de execucao antes de alterar spec/codigo.

Revision Log

• 2026-04-09: Initial accepted decision from AGD-0019.