prometeu-runtime/discussion/workflow/agendas/AGD-0019-asset-entry-codec-enum-with-metadata.md

id	ticket	title	status	created	resolved	decision	tags
AGD-0019	asset-entry-codec-enum-with-metadata	Agenda - Asset Entry Codec as Enum with Metadata	accepted	2026-04-09	2026-04-09	DEC-0005	asset runtime codec metadata

Agenda - Asset Entry Codec as Enum with Metadata

Contexto

A DSC-0017 consolidou a normalizacao de AssetEntry.metadata, separando campos criticos na raiz e empurrando detalhes tecnicos para subarvores como codec e pipeline.

Isso resolveu a organizacao do contrato, mas nao fechou a representacao tipada de codec dentro do runtime. Hoje o dado ainda e percebido mais como JSON dinamico do que como parte explicita do modelo de dominio.

O tema desta agenda e decidir se codec em AssetEntry deve deixar de ser apenas um blob/subarvore e passar a ser um enum tipado, capaz de carregar os metadados pertinentes a cada codec.

Problema

Quando codec e tratado como JSON generico ou como informacao frouxa em metadados, o runtime perde:

• clareza sobre quais codecs existem de fato;
• validacao estrutural forte por variante;
• ergonomia para loaders e drivers;
• separacao nitida entre metadata do banco e metadata do codec.

Ao mesmo tempo, tipar codec cedo demais ou de forma larga demais pode misturar responsabilidades e transformar o enum em um deposito generico de qualquer detalhe tecnico do asset.

Pontos Criticos

1. Limite de responsabilidade. codec deve carregar apenas dados necessarios para decodificacao, nao toda a metadata do asset.

2. Compatibilidade com a normalizacao anterior. A agenda nao deve reabrir a decisao de segmentar metadata; ela deve apenas fechar como o segmento codec vira modelo tipado no runtime.

3. Evolucao de formato. O modelo precisa permitir codecs sem payload adicional e codecs com configuracao especifica, sem cair em campos opcionais demais.

4. Unknown/forward compatibility. Precisamos decidir se codecs desconhecidos falham no parse, se ficam preservados como raw JSON, ou se existe modo hibrido.

5. Impacto nos callers. A mudanca afeta serializacao/deserializacao, helpers, validacao de cart e ergonomia dos loaders.

Opcoes

Opcao A - Manter codec como JSON dinamico

• Abordagem: manter codec como subarvore em metadata ou como serde_json::Value, usando helpers tipados apenas nos pontos de consumo.
• Pro: menor migracao imediata e maior flexibilidade para formatos experimentais.
• Con: o contrato real continua implicito, com checagens espalhadas e mais risco de drift entre parser e consumidores.
• Tradeoff: adia a decisao de dominio e preserva a ambiguidade exatamente no ponto onde o runtime precisa de semantica forte.

Opcao B - Tornar codec um enum tipado com payload por variante

• Abordagem: introduzir algo como AssetCodec, com variantes explicitas (None, Png { ... }, Jpeg { ... }, etc.) carregando apenas os metadados do proprio codec.
• Pro: o runtime ganha exaustividade, parse centralizado e um modelo de dominio mais honesto.
• Con: exige decidir fronteiras claras entre metadata do codec e metadata do banco/asset; tambem aumenta custo de evolucao quando novos codecs surgem.
• Tradeoff: troca flexibilidade irrestrita por contrato forte e melhor ergonomia operacional.

Opcao C - Separar codec_kind de um payload opcional tipado

• Abordagem: usar um enum leve para o tipo de codec e um campo separado para configuracao adicional.
• Pro: reduz acoplamento do discriminante com o payload e pode simplificar alguns formatos.
• Con: reintroduz estados invalidos (kind e payload divergentes), exigindo validacao cruzada manual.
• Tradeoff: parece mais flexivel, mas perde a principal vantagem de um tagged enum: coerencia estrutural por construcao.

Sugestao / Recomendacao

Seguir com a Opcao B.

codec em AssetEntry deveria ser um enum tipado e capaz de carregar os metadados estritamente relativos a ele. Isso fecha melhor o modelo de dominio: o runtime deixa de tratar codec como detalhe textual solto e passa a reconhece-lo como parte semantica do contrato do asset.

A recomendacao, no entanto, vem com uma fronteira explicita:

• metadata especifica de decodificacao fica dentro do enum do codec;
• metadata do banco/formato de consumo continua fora dele;
• metadata editorial ou operacional do asset tambem continua fora dele.

Em outras palavras, a discussao nao e "colocar toda metadata dentro de codec", e sim "dar ao segmento codec uma representacao tipada, exaustiva e com payload por variante quando necessario".

Com as respostas atuais, a recomendacao fica mais concreta:

• o JSON serializado pelo Studio dentro de asset.pa pode manter codec como string opaca;
• o runtime Rust deve desserializar essa string diretamente para um enum em AssetEntry;
• o nome canonico de cada codec no JSON deve seguir o contrato definido pelo runtime, e o Studio/paker deve se conformar exatamente a ele;
• a variante inicial canonica e apenas None;
• Raw deve ser considerada removida do modelo;
• codec desconhecido no runtime e erro fatal de carregamento e deve impedir a execucao do cartucho;
• pipeline nao deve sobreviver no runtime e pode ser descartado completamente desse lado.

Perguntas em Aberto

• Como o modelo evolui quando surgir o primeiro codec real com payload adicional sem perder a separacao entre o discriminante string no JSON e a interpretacao tipada no runtime?

Discussao

Direcao fechada ate aqui

1. Serializacao no Studio O JSON serializado pelo Studio dentro de asset.pa deve expor codec como string opaca.

2. Desserializacao no runtime O runtime Rust deve carregar essa string diretamente em um enum no proprio AssetEntry. O wire format continua string, mas o modelo carregado no runtime passa a ser tipado.

3. Canon do nome O nome textual do codec no JSON nao e arbitrario por produtor. Ele deve seguir exatamente o canon definido pelo contrato. O canon fechado para este tema e SCREAMING_SNAKE_CASE, alinhado a BankType, e o packer deve seguir esse formato sem aliases livres.

4. Variante inicial O unico codec canonico agora e None.

5. Fim de Raw Raw nao deve mais existir como conceito no modelo.

6. Codecs desconhecidos Nao devem ser empacotados. Se mesmo assim chegarem ao runtime, isso e erro de validacao do AssetEntry e o cartucho deve ser fechado antes de seguir.

7. Escopo atual de codecs Como ainda nao existe codec real implementado, a primeira versao do enum pode ser minima e conter apenas None.

8. Destino de pipeline pipeline nao tem valor operacional no runtime atual e pode ser descartado completamente desse lado.

Leitura arquitetural dessas respostas

As respostas empurram a agenda para um contrato bem mais estrito do que o texto inicial sugeria:

• codec existe como conceito de dominio mesmo antes de haver codecs concretos alem de None;
• o JSON de asset.pa pode manter um discriminante simples e opaco, enquanto o runtime desserializa isso diretamente para enum e usa esse valor para escolher a interpretacao tipada de metadata.codec;
• a autoridade sobre o spelling do codec pertence ao contrato compartilhado, nao ao Studio isoladamente;
• o runtime nao deve carregar extensibilidade aberta para codecs desconhecidos;
• a compatibilidade futura deve ser dirigida pelo Studio e pelo empacotamento, nao por tolerancia dinamica no runtime;
• pipeline deixa de disputar espaco conceitual com codec no runtime.

Isso favorece um modelo de enum fechado, validado cedo e com semantica fail-fast.

Criterio para Encerrar

Esta agenda pode ser encerrada quando houver consenso escrito sobre:

• o papel exato de codec no modelo de dominio do AssetEntry;
• a fronteira entre payload do codec e restante da metadata;
• a estrategia para codecs sem metadata adicional e para codecs desconhecidos;
• o shape string de codec no JSON e sua relacao com o enum carregado no runtime e com metadata.codec;
• o proximo passo normativo para transformar isso em decisao sem reabrir DSC-0017.

Resolucao Provisoria

Ha consenso provisoriamente estabelecido sobre os seguintes pontos:

• codec deve existir como enum tipado no modelo do runtime;
• a variante inicial unica e None;
• Raw sai do contrato;
• codecs desconhecidos sao invalidos e devem falhar de forma fatal no carregamento do cartucho;
• pipeline pode ser descartado do runtime;
• o JSON de asset.pa deve serializar codec como string opaca;
• o runtime Rust deve desserializar essa string diretamente para enum no AssetEntry;
• o nome textual do codec no JSON deve seguir SCREAMING_SNAKE_CASE, e o Studio deve se conformar exatamente a ele;
• codec desconhecido deve falhar na validacao do AssetEntry, antes de qualquer carga efetiva.

O unico ponto em aberto passa a ser a politica de evolucao para o primeiro codec real com payload, preservando a distincao entre:

• discriminante string no JSON do asset; e
• shape tipado de metadata.codec no runtime.

Resolucao

A agenda fica encerrada com a seguinte orientacao:

• codec permanece string no JSON de asset.pa;
• o runtime Rust deve desserializar essa string diretamente para enum no AssetEntry;
• o nome textual do codec segue SCREAMING_SNAKE_CASE, alinhado a BankType;
• None e a unica variante inicial;
• Raw sai do contrato;
• codec desconhecido falha na validacao do AssetEntry e fecha o cartucho;
• pipeline e descartado do runtime.

A evolucao para codecs com payload adicional fica explicitamente adiada para uma decisao futura motivada por um codec real.