61 lines
2.1 KiB
Markdown
61 lines
2.1 KiB
Markdown
# 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.
|