asset preload alignment
This commit is contained in:
@@ -0,0 +1,29 @@
|
||||
# Agenda 024 - `assets.pa` Preload and Asset Table ID-based Contract (Fechada)
|
||||
|
||||
## Status
|
||||
|
||||
Fechada pela decisao:
|
||||
|
||||
- `../decisions/012-assets-preload-asset-id-contract.md`
|
||||
|
||||
## O Que Foi Fechado
|
||||
|
||||
1. `PreloadEntry` deixa de usar `asset_name` e passa a ser normativamente `{ asset_id, slot }`.
|
||||
2. `asset_id` passa a ser o identificador operacional de preload com semantica de `java int`.
|
||||
3. `asset_name` permanece apenas como metadata descritiva/debug e nao participa do preload.
|
||||
4. `preload` deve ser validado contra a `asset_table` do proprio `assets.pa` durante o bootstrap.
|
||||
5. `asset_id` ausente da `asset_table` e clash de slot por tipo caracterizam erro estrutural de formacao do cart.
|
||||
6. Nao existe compatibilidade normativa para preload legado por `asset_name`.
|
||||
|
||||
## Efeito Pratico
|
||||
|
||||
- `spec 15` passa a precisar explicitar o shape normativo de `PreloadEntry` e a validacao estrutural de preload.
|
||||
- loader, parser de `assets.pa` e `AssetManager` passam a consumir preload por `asset_id`.
|
||||
- a modelagem atual em codigo baseada em `u32` para `asset_id` precisa ser revisitada onde o contrato exposto ainda assume unsigned.
|
||||
|
||||
## Follow-up
|
||||
|
||||
- propagar a decisao em `specs 13/15`;
|
||||
- criar suporte de parse/validacao estrutural para preload por `asset_id`;
|
||||
- remover o preload por `asset_name` do runtime e dos testes;
|
||||
- manter `asset.load(name, kind, slot)` inalterado ate decisao futura sobre a superficie VM-facing.
|
||||
@@ -24,7 +24,6 @@ As agendas atuais são:
|
||||
- `020-perf-host-debug-overlay-isolation.md`
|
||||
- `021-perf-vm-allocation-and-copy-pressure.md`
|
||||
- `022-perf-cartridge-boot-and-program-ownership.md`
|
||||
|
||||
## Sequenciamento Recomendado [PERF]
|
||||
|
||||
Ordem sugerida para discussao das agendas de performance:
|
||||
|
||||
@@ -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/`):
|
||||
|
||||
|
||||
@@ -0,0 +1,69 @@
|
||||
# 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.
|
||||
@@ -38,3 +38,4 @@ Uma PR deste diretório deve:
|
||||
|
||||
PRs propostas para execucao da rodada atual:
|
||||
|
||||
- `012-assets-preload-asset-id-propagation.md`
|
||||
|
||||
@@ -109,6 +109,13 @@ The JSON header carries:
|
||||
|
||||
`asset_table` and `preload` are therefore no longer the primary runtime contract of `manifest.json`.
|
||||
|
||||
`preload` is structurally validated as part of `assets.pa` bootstrap:
|
||||
|
||||
- each preload entry is `{ asset_id, slot }`;
|
||||
- `asset_id` uses 32-bit signed integer semantics;
|
||||
- each `preload.asset_id` must resolve to an entry in the same `asset_table`;
|
||||
- no two preload entries may claim the same `(bank_type, slot)` pair once `bank_type` is resolved from `asset_table`.
|
||||
|
||||
Runtime lifecycle:
|
||||
|
||||
- `asset_table` is loaded from `assets.pa` and remains live while the cartridge is running;
|
||||
@@ -119,6 +126,7 @@ Runtime loading policy:
|
||||
|
||||
- cartridges without `assets.pa` remain valid when `Asset` capability is not declared;
|
||||
- cartridges that declare `Asset` capability must provide valid `assets.pa`;
|
||||
- `assets.pa` with invalid preload references or preload slot clashes is structurally invalid;
|
||||
- failure must occur as early as cartridge bootstrap, before preload execution.
|
||||
|
||||
## 7 Runtime Forms
|
||||
|
||||
@@ -96,6 +96,8 @@ AssetEntry {
|
||||
|
||||
This table describes content identity and storage layout, not live residency.
|
||||
|
||||
`asset_id` is the stable runtime-facing asset identity and uses 32-bit signed integer semantics compatible with Java `int`.
|
||||
|
||||
`offset` is relative to the start of the payload region inside `assets.pa`.
|
||||
|
||||
## 5 Banks and Slots
|
||||
@@ -180,13 +182,33 @@ These metrics support debugging, telemetry, and certification-oriented inspectio
|
||||
|
||||
`preload` is stored in the JSON header of `assets.pa`.
|
||||
|
||||
The normative preload shape is:
|
||||
|
||||
```text
|
||||
PreloadEntry {
|
||||
asset_id
|
||||
slot
|
||||
}
|
||||
```
|
||||
|
||||
These preload entries are consumed during cartridge initialization so the asset manager can establish initial residency before normal execution flow.
|
||||
|
||||
Validation rules:
|
||||
|
||||
- `preload` is resolved by `asset_id`, not by `asset_name`;
|
||||
- every `preload.asset_id` must exist in the same `asset_table`;
|
||||
- no two preload entries may resolve to the same `(bank_type, slot)` pair;
|
||||
- legacy preload keyed by `asset_name` is invalid for the current contract.
|
||||
|
||||
Lifecycle rule:
|
||||
|
||||
- `preload` is boot-time input only;
|
||||
- it does not need to remain live after initialization completes.
|
||||
|
||||
Bootstrap rule:
|
||||
|
||||
- invalid preload is a structural cartridge error and must fail cartridge bootstrap before normal execution begins.
|
||||
|
||||
## 10 Relationship to Other Specs
|
||||
|
||||
- [`13-cartridge.md`](13-cartridge.md) defines the cartridge package and the requirement that `assets.pa` carries its own asset header.
|
||||
|
||||
Reference in New Issue
Block a user