---
id: DEC-0005
ticket: asset-entry-codec-enum-with-metadata
title: Asset Entry Codec Enum Contract
status: accepted
created: 2026-04-09
accepted: 2026-04-09
agenda: AGD-0019
plans: [PLN-0004]
tags: [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.