prometeu-runtime/docs/runtime/pull-requests/012-assets-preload-asset-id-propagation.md

PR 012 - Propagacao da Decision 012 para Preload por asset_id

Briefing

Esta PR executa a decision 012, que fecha a identidade normativa de preload em assets.pa.

O objetivo e remover preload por asset_name, adotar asset_id com semantica de java int, e validar preload como parte estrutural da formacao do cart.

Decisions de Origem

• ../decisions/011-assets-pa-autocontained-runtime-contract.md
• ../decisions/012-assets-preload-asset-id-contract.md

Alvo

Propagar a decisao em specs e codigo do runtime para que:

• PreloadEntry seja { asset_id, slot };
• preload invalido falhe no bootstrap;
• o runtime nao dependa de nome para resolver preload.

Escopo

• atualizar spec 13 e spec 15;
• atualizar structs e parse do header de assets.pa;
• validar preload contra asset_table;
• detectar clash de slot por tipo;
• ajustar AssetManager e testes para preload por asset_id;
• revisar tipos expostos de asset_id para semantica de java int.

Fora de Escopo

• mudar a superficie VM-facing de asset.load(name, kind, slot);
• redesenhar asset_table alem do necessario para suportar a decisao;
• introduzir compatibilidade legado por asset_name;
• alterar politica de bancos/slots fora da validacao de preload.

Plano de Execucao

1. Atualizar specs 13 e 15 com o shape normativo novo e as regras de validacao estrutural.
2. Trocar PreloadEntry em prometeu-hal para asset_id.
3. Revisar os pontos runtime-facing onde asset_id ainda esta fixado como unsigned.
4. Validar, no parse/bootstrap de assets.pa, que:
   • todo preload referencia asset_id existente;
   • nao existe duplicidade de (bank_type, slot).
5. Remover a resolucao nome -> id do caminho de preload no AssetManager.
6. Atualizar testes de loader, parse e preload em memoria.

Criterios de Aceite

• assets.pa com preload valido por asset_id carrega normalmente.
• assets.pa com asset_id ausente da asset_table falha no bootstrap.
• assets.pa com clash de slot por tipo falha no bootstrap.
• preload deixa de depender de asset_name.
• nenhuma spec vigente continua descrevendo preload por nome.

Tests / Validacao

• teste de parse do header com PreloadEntry { asset_id, slot };
• teste de rejeicao para preload.asset_id inexistente;
• teste de rejeicao para duplicidade de (bank_type, slot);
• teste de inicializacao do AssetManager preloading por asset_id;
• revisao textual das specs 13 e 15 contra a decision 012.

Riscos

• a troca de semantica de asset_id para java int pode expor assumptos unsigned espalhados no runtime;
• validacao estrutural no loader pode exigir ajuste em fixtures de teste existentes;
• se houver produtor externo ainda emitindo preload por asset_name, ele quebrara imediatamente, como mandado pela decisao.