92 lines
5.2 KiB
Markdown
92 lines
5.2 KiB
Markdown
---
|
|
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.
|