prometeu-runtime/docs/runtime/pull-requests/PR-011a-assets-pa-autocontained-spec-propagation.md

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.