dev/ajustments-asset-entry (#12)
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good

Reviewed-on: #12
Co-authored-by: bQUARKz <bquarkz@gmail.com>
Co-committed-by: bQUARKz <bquarkz@gmail.com>
This commit was merged in pull request #12.
This commit is contained in:
2026-04-10 05:31:57 +00:00
committed by bquarkz
parent c4aca95635
commit 035e9d5676
32 changed files with 584 additions and 813 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: `GlyphsMetadata`, `SoundsMetadata`) que representam o contrato exato de cada banco.
2. **Conversion Methods**: Adicionamos métodos ao `AssetEntry` (ex: `metadata_as_glyphs()`) 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`