asset preload alignment
This commit is contained in:
@@ -0,0 +1,157 @@
|
||||
# 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.
|
||||
@@ -20,6 +20,7 @@ Decisoes ativas:
|
||||
- `006-vm-owned-stateful-core-contract.md`
|
||||
- `007-filesystem-fault-core-policy.md`
|
||||
- `011-assets-pa-autocontained-runtime-contract.md`
|
||||
- `012-assets-preload-asset-id-contract.md`
|
||||
|
||||
Decisoes implementadas e aposentadas (migradas para `learn/`):
|
||||
|
||||
|
||||
Reference in New Issue
Block a user