# 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:

```text
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:

```text
(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.