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