94 lines
3.8 KiB
Markdown
94 lines
3.8 KiB
Markdown
# PR - Assets.pa Autocontained Spec Propagation
|
|
|
|
## Briefing
|
|
|
|
A decisao `011-assets-pa-autocontained-runtime-contract.md` fechou o contrato arquitetural de `assets.pa` como artefato runtime-facing autocontido.
|
|
|
|
Agora o runtime precisa publicar esse contrato em spec para que:
|
|
|
|
- `../runtime` tenha base normativa consolidada;
|
|
- o `studio` possa evoluir o packer em paralelo sem depender de heuristica local;
|
|
- a PR de codigo implemente um contrato ja estabilizado.
|
|
|
|
Esta PR e editorial/normativa. Ela nao rediscute a arquitetura da decisao `011`.
|
|
|
|
## Decisions de Origem
|
|
|
|
- `../decisions/011-assets-pa-autocontained-runtime-contract.md`
|
|
|
|
## Alvo
|
|
|
|
Propagar a decisao `011` para o corpus normativo do runtime, principalmente:
|
|
|
|
- `../specs/13-cartridge.md`
|
|
- `../specs/15-asset-management.md`
|
|
|
|
## Escopo
|
|
|
|
- mover `asset_table` e `preload` para dentro do contrato de `assets.pa`;
|
|
- descrever `assets.pa` v1 como:
|
|
- prelude binario fixo;
|
|
- header JSON;
|
|
- payload binario;
|
|
- registrar prelude minimo:
|
|
- `magic`
|
|
- `schema_version`
|
|
- `header_len`
|
|
- `payload_offset`
|
|
- registrar opcionais permitidos:
|
|
- `flags`
|
|
- `reserved`
|
|
- `header_checksum`
|
|
- fixar que offsets de `AssetEntry` sao relativos ao inicio da regiao de payload;
|
|
- fixar lifecycle:
|
|
- `preload` so no boot;
|
|
- `asset_table` viva durante a execucao do cart;
|
|
- fixar leitura sob demanda por slice (`open_slice` como conceito normativo);
|
|
- fixar `OP_MODE` derivado de `codec`/CODEX no v1;
|
|
- fixar falha antecipada quando `Capability::Asset` exigir `assets.pa` ausente.
|
|
|
|
## Fora de Escopo
|
|
|
|
- alterar codigo do loader, firmware ou `AssetManager`;
|
|
- implementar `.pmc`;
|
|
- definir formato dos JSONs auxiliares do `shipper` alem de seu status nao normativo para runtime;
|
|
- introduzir novos codecs ou alterar o shape semantico de `AssetEntry` e `PreloadEntry`;
|
|
- escrever a spec do packer no `studio`.
|
|
|
|
## Plano de Execucao
|
|
|
|
1. Atualizar `13-cartridge.md` para:
|
|
- remover `asset_table` e `preload` como superficie primaria de runtime no manifest;
|
|
- descrever `assets.pa` como artefato autocontido;
|
|
- registrar a regra de falha antecipada ligada a `Capability::Asset`.
|
|
2. Atualizar `15-asset-management.md` para:
|
|
- descrever o envelope de `assets.pa`;
|
|
- distinguir lifecycle de `preload` e `asset_table`;
|
|
- registrar offsets relativos ao payload;
|
|
- registrar leitura sob demanda por slice;
|
|
- registrar `OP_MODE` por codec/CODEX.
|
|
3. Revisar cross-references entre `13`, `15` e `16`.
|
|
4. Garantir que a linguagem normativa deixe claro o que e contrato runtime-facing e o que e apenas helper para o `shipper`.
|
|
|
|
## Criterios de Aceite
|
|
|
|
- `13-cartridge.md` nao apresenta mais `asset_table` e `preload` como contrato primario do manifest consumido pelo runtime.
|
|
- `15-asset-management.md` descreve `assets.pa` como artefato autocontido com prelude, header e payload.
|
|
- a spec fixa offsets relativos ao payload, nao ao arquivo inteiro.
|
|
- a spec fixa que `preload` e dado transitorio de boot e `asset_table` permanece viva durante a execucao do cart.
|
|
- a spec fixa leitura sob demanda do payload, sem baseline de blob inteiro residente em RAM.
|
|
- a spec fixa falha antecipada quando `Capability::Asset` exigir `assets.pa` ausente.
|
|
- a linguagem publicada e suficiente para o Studio implementar o packer em paralelo sem depender do codigo do runtime.
|
|
|
|
## Tests / Validacao
|
|
|
|
- revisao editorial cruzada entre `13` e `15` para garantir ausencia de contradicao;
|
|
- revisao de consistencia com a decisao `011`;
|
|
- conferência de que a PR de codigo derivada consegue citar trechos normativos concretos sem reinterpretacao arquitetural.
|
|
|
|
## Riscos
|
|
|
|
- deixar resquicios do modelo antigo (`asset_table`/`preload` no manifest) em texto normativo;
|
|
- documentar `open_slice` e `OP_MODE` de forma vaga demais, prejudicando a implementacao;
|
|
- deixar lacuna suficiente para que o Studio reabra localmente a autoridade dos JSONs auxiliares.
|