Asset Entry Metadata Normalization Contract

This commit is contained in:
2026-04-09 08:25:37 +01:00
parent 9228fb1e29
commit 52d4a91c71
6 changed files with 110 additions and 138 deletions
@@ -0,0 +1,33 @@
# LSN-0023: Typed Helpers for Asset Metadata
Status: Published
Decisions: [[DEC-0004]]
Tags: [asset, runtime, rust, pattern]
## Contexto
A decisão [[DEC-0004]] estabeleceu um contrato de metadados segmentados para assets, mantendo campos críticos na raiz do JSON e detalhes técnicos em subárvores (`codec`, `pipeline`). No entanto, o `AssetEntry.metadata` no runtime é um `serde_json::Value` dinâmico.
## Lição
O uso de `serde_json::Value` diretamente nos loaders do runtime introduz riscos de runtime (erros de tipo, campos ausentes) e polui o código com chamadas repetitivas de `.get()`, `.as_u64()`, etc.
### Abordagem Adotada
Para mitigar isso, implementamos o padrão de **Typed Metadata Helpers**:
1. **Structs Dedicadas**: Criamos structs Rust (ex: `TilesMetadata`, `SoundsMetadata`) que representam o contrato exato de cada banco.
2. **Conversion Methods**: Adicionamos métodos ao `AssetEntry` (ex: `metadata_as_tiles()`) que utilizam `serde_json::from_value` para realizar o "cast" do JSON dinâmico para a struct tipada.
3. **Fail-Fast**: A falha no parsing dos metadados deve ser tratada como erro de carregamento do asset, garantindo que o motor não opere com metadados corrompidos ou incompletos.
### Benefícios
- **Segurança de Tipo**: Erros de estrutura de metadados são detectados no momento do carregamento.
- **Ergonomia**: O código dos drivers passa a usar `meta.tile_size` em vez de parsing manual.
- **Desacoplamento**: A complexidade do JSON fica encapsulada nos helpers de conversão.
## Referências
- DEC-0004: Asset Entry Metadata Normalization Contract
- `prometeu-hal/src/asset.rs`
- `prometeu-drivers/src/asset.rs`