prometeu-runtime/docs/runtime/decisions/012-assets-preload-asset-id-contract.md

Decision Record - assets.pa Preload Uses asset_id

Status

Accepted

Contexto

A decision 011 fechou o envelope runtime-facing de assets.pa:

• assets.pa e o contrato primario de assets do runtime;
• asset_table e preload vivem no header interno do artefato;
• preload e consumido apenas no bootstrap.

Essa decisao, no entanto, nao definiu a semantica de identidade de PreloadEntry.

O estado atual do runtime ainda mistura dois modelos:

• AssetEntry ja trata asset_id como identidade operacional do asset;
• PreloadEntry ainda usa asset_name como chave pratica de resolucao no boot.

Isso preserva uma dependencia estrutural de campo mutavel justamente na fase em que o cart deveria ser mais deterministicamente validavel.

Decisao

1. PreloadEntry passa a ser { asset_id, slot }

O shape normativo de preload em assets.pa passa a ser:

PreloadEntry {
  asset_id,
  slot
}

asset_name deixa de fazer parte do contrato operacional de preload.

2. asset_id tem semantica de java int

asset_id no contrato runtime-facing de assets passa a ser um inteiro de 32 bits com semantica de java int.

Qualquer representacao interna do runtime deve respeitar essa semantica e nao introduzir contrato unsigned por acidente.

3. asset_name permanece apenas como metadata descritiva

asset_name continua permitido em AssetEntry para:

• debug;
• observabilidade;
• tooling editorial;
• UX de inspecao.

Mas asset_name nao participa:

• da identidade normativa do asset;
• da validacao de preload;
• da resolucao operacional de preload.

4. preload deve ser validado contra a asset_table

Quando assets.pa existir, o runtime deve validar preload durante o bootstrap usando a asset_table carregada do mesmo artefato.

Validacoes minimas obrigatorias:

• todo preload.asset_id deve existir na asset_table;
• nao pode haver clash de slot por tipo.

5. Clash de slot por tipo e proibido

O namespace de slot de preload e derivado de bank_type da asset_table.

Portanto, depois de resolver cada preload.asset_id para sua respectiva AssetEntry, o cart e invalido se houver mais de uma entry de preload para o mesmo par:

(bank_type, slot)

Isso vale mesmo que as entries apontem para o mesmo asset.

6. Nao ha compatibilidade normativa com preload legado por asset_name

O contrato do runtime nao oferece modo de compatibilidade para preload legado baseado em asset_name.

Artefatos que nao seguirem o shape novo devem ser considerados invalidos para o contrato vigente.

7. Falhas de preload invalido sao estruturais de cart

Os seguintes casos sao erros estruturais de formacao do cart:

• preload.asset_id ausente da asset_table;
• clash de slot por tipo dentro de preload.

Esses casos devem falhar no bootstrap do cart, antes da execucao normal, e nao pertencem ao espaco de status operacional de asset.load.

Rationale

Esta decisao foi adotada porque:

• alinha preload com a identidade estavel do dominio de assets;
• remove dependencia de metadata mutavel no bootstrap;
• preserva asset_table como fonte de verdade unica para identidade e tipo;
• torna a validacao do cart mais deterministica;
• impede que compatibilidade legado vire contrato permanente por inercia.

O uso de java int foi escolhido para manter alinhamento de semantica de ID com a fronteira de linguagem/plataforma desejada, em vez de cristalizar um detalhe unsigned especifico da implementacao atual em Rust.

Invariantes / Contrato

• PreloadEntry e normativamente { asset_id, slot }.
• asset_id segue semantica de java int.
• asset_name nao tem autoridade operacional sobre preload.
• preload so pode referenciar assets existentes na asset_table do mesmo assets.pa.
• preload nao pode conter mais de uma ocupacao para o mesmo par (bank_type, slot).
• falhas de validacao de preload sao erros estruturais de cart e devem abortar o bootstrap.
• asset.load(name, kind, slot) permanece fora do escopo desta decisao.

Impactos

Specs

• 15-asset-management.md deve explicitar o shape normativo de PreloadEntry, a semantica de asset_id e as validacoes estruturais de preload.
• 13-cartridge.md deve registrar que assets.pa invalido inclui preload com IDs ausentes ou clash de slot por tipo.

Runtime

• prometeu-hal/src/asset.rs deve trocar PreloadEntry.asset_name por asset_id.
• tipos de asset_id expostos no contrato runtime-facing devem ser revisados para semantica de java int.
• o loader de assets.pa deve rejeitar preload invalido antes de iniciar preload.
• o AssetManager deve resolver preload diretamente por asset_id, sem ponte nome -> id.

Tooling / Packer

• o produtor de assets.pa deve emitir preload apenas com asset_id.
• carts com preload legado por asset_name deixam de ser validos no contrato atual.

Referencias

• ../agendas/024-assets-pa-preload-and-asset-table-id-based-contract.md
• ../decisions/011-assets-pa-autocontained-runtime-contract.md
• ../specs/13-cartridge.md
• ../specs/15-asset-management.md
• ../../crates/console/prometeu-hal/src/asset.rs
• ../../crates/console/prometeu-hal/src/cartridge_loader.rs
• ../../crates/console/prometeu-drivers/src/asset.rs

Propagacao Necessaria

• criar PR/plan para atualizar spec 13 e spec 15;
• criar PR/plan de codigo para:
  • trocar o shape de PreloadEntry para asset_id;
  • validar preload durante parse/bootstrap de assets.pa;
  • rejeitar asset_id ausente da asset_table;
  • rejeitar clash de slot por tipo;
  • revisar a tipagem de asset_id para semantica de java int;
  • atualizar testes de loader e AssetManager;
• remover a agenda 024 da lista de agendas ativas.