prometeu-runtime/docs/runtime/pull-requests/PR-011c-assets-pa-payload-source-and-open-slice.md

PR - Assets.pa Payload Source and Open Slice

Briefing

Depois que o bootstrap souber abrir assets.pa e materializar seu header, o runtime precisa parar de tratar o payload como Vec<u8> residente por padrao.

Esta PR introduz a fronteira de leitura sob demanda do payload, sem ainda acoplar isso ao refactor completo do AssetManager.

Decisions de Origem

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

Alvo

Introduzir a origem de payload por slice e a primitiva equivalente a open_slice(offset, size).

Escopo

• introduzir uma abstracao de origem de payload para assets.pa;
• suportar abertura de slices limitados por offset relativo ao payload;
• preservar payload_offset resolvido no bootstrap;
• permitir leitura a partir de ROM/storage sem materializar o assets.pa inteiro;
• preparar a integracao posterior com AssetManager e CODEX.

Fora de Escopo

• alterar semantica observavel de asset.load/status/commit/cancel;
• refatorar decode de TILES e SOUNDS para OP_MODE final;
• preload;
• .pmc;
• novos codecs.

Plano de Execucao

1. Introduzir a abstracao de source/view do payload.
2. Implementar open_slice(offset, size) sobre offsets relativos ao payload.
3. Garantir que a camada proteja contra leitura fora da faixa do payload.
4. Conectar bootstrap e modelo Cartridge a essa nova origem de payload.

Criterios de Aceite

• o runtime possui uma abstracao explicita para abrir slices do payload.
• open_slice resolve offsets relativos ao payload, nao ao arquivo inteiro.
• o payload inteiro nao precisa ser carregado em RAM para o runtime operar.
• a nova abstracao e suficiente para alimentar o refactor do AssetManager na PR seguinte.

Tests / Validacao

• testes unitarios de open_slice para:
  • offset valido;
  • offset fora da faixa;
  • size fora da faixa;
  • slice no fim do payload;
• testes de integracao minima garantindo que o bootstrap entrega uma origem de payload funcional.

Riscos

• escolher uma abstracao acoplada demais ao filesystem local;
• introduzir API de source/view insuficiente para codecs futuros;
• vazar detalhe de offset absoluto para camadas superiores.