158 lines
5.6 KiB
Markdown
158 lines
5.6 KiB
Markdown
# 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.
|