prometeu-runtime/docs/runtime/pull-requests/PR-011b-assets-pa-bootstrap-and-header-loading.md

PR - Assets.pa Bootstrap and Header Loading

Briefing

A decisao 011-assets-pa-autocontained-runtime-contract.md exige que o runtime deixe de depender de asset_table e preload no manifest.json e passe a materializar essas estruturas a partir do header de assets.pa.

O primeiro passo de codigo deve atacar apenas bootstrap e carga de header, sem misturar isso com a mudanca maior de leitura sob demanda do payload.

Esta PR existe para fechar cedo:

• falha antecipada quando Capability::Asset exigir assets.pa ausente;
• parse do prelude binario e do header JSON;
• materializacao de asset_table e preload a partir de assets.pa.

Decisions de Origem

• ../decisions/011-assets-pa-autocontained-runtime-contract.md

Alvo

Implementar o novo caminho de bootstrap e leitura do header de assets.pa.

Escopo

• atualizar cartridge_loader.rs para reconhecer assets.pa como binario autocontido;
• introduzir parse do prelude binario fixo;
• introduzir parse do header JSON;
• remover dependencia primaria de asset_table e preload no manifest.json;
• atualizar cartridge.rs para refletir a nova origem da metadata;
• falhar cedo quando Capability::Asset estiver declarada e assets.pa estiver ausente;
• disponibilizar asset_table, preload, payload_offset e origem de assets.pa para as etapas seguintes do runtime.

Fora de Escopo

• leitura sob demanda por slice;
• refactor do AssetManager para deixar de depender de blob inteiro;
• integracao de OP_MODE com CODEX;
• .pmc;
• novos codecs.

Plano de Execucao

1. Implementar parsing do envelope:
   • prelude binario;
   • header JSON;
   • payload base offset.
2. Atualizar o modelo Cartridge para parar de tratar asset_table e preload como dados vindos primariamente do manifest.
3. Alterar o bootstrap do cart para:
   • materializar manifest.json;
   • checar cedo Capability::Asset vs presenca de assets.pa;
   • abrir assets.pa;
   • carregar asset_table e preload do header.
4. Preservar compatibilidade do restante do runtime com a nova origem dos dados, sem ainda mexer na estrategia de payload.

Criterios de Aceite

• asset_table e preload passam a vir do header de assets.pa.
• o runtime falha cedo quando Capability::Asset estiver presente e assets.pa estiver ausente.
• carts sem Capability::Asset continuam validos sem assets.pa.
• manifest.json deixa de ser a fonte primaria de asset_table e preload.
• o envelope de assets.pa e parseado de forma consistente com a decisao 011.

Tests / Validacao

• testes de loader para:
  • assets.pa ausente com e sem Capability::Asset;
  • prelude invalido;
  • header JSON invalido;
  • parse valido de asset_table e preload;
• testes de boot para garantir falha antecipada antes de preload quando o artefato exigido nao existir.

Riscos

• deixar fallback implicito para metadata no manifest.json;
• falhar tarde demais na ausencia de assets.pa;
• acoplar parse do envelope a detalhes de filesystem antes de introduzir uma fonte de payload mais limpa.