This commit is contained in:
@@ -1,91 +0,0 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user