added asset loading PRs
This commit is contained in:
parent
683d291afd
commit
4737e65f5a
SSH Key Fingerprint:
SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
@ -1,181 +0,0 @@
|
||||
# Agenda - Asset Packer Runtime-Facing Contract
|
||||
|
||||
## Contexto
|
||||
|
||||
Hoje o runtime ja consome uma superficie de assets relativamente clara:
|
||||
|
||||
- `asset_table` no `manifest.json`;
|
||||
- `assets.pa` como blob packed de bytes frios;
|
||||
- `preload` opcional para residency inicial.
|
||||
|
||||
Essa superficie esta descrita em `13-cartridge.md` e `15-asset-management.md`, mas ainda do ponto de vista do consumidor runtime.
|
||||
|
||||
Falta fechar a fronteira do produtor de `assets.pa`.
|
||||
|
||||
Para o repositorio, a nomenclatura precisa ficar explicita:
|
||||
|
||||
- `shipper` monta o cart distribuivel e e responsavel pelo `.pmc`;
|
||||
- `packer` empacota somente os assets e produz a superficie que alimenta `asset_table` + `assets.pa`;
|
||||
- `compiler` e outros workers entram como dependencias do `shipper`, nao como substitutos do `packer`.
|
||||
|
||||
Sem essa separacao, a discussao de `.pmc` tende a misturar container de distribuicao com contrato de bytes/metadata dos assets.
|
||||
|
||||
## Problema
|
||||
|
||||
O runtime conhece `assets.pa`, mas o projeto ainda nao decidiu qual e a facing do `packer` que produz esse artefato.
|
||||
|
||||
Hoje nao esta fechado:
|
||||
|
||||
- qual e a entrada canonica do packer;
|
||||
- qual e a saida normativa alem do blob cru;
|
||||
- como `asset_id`, `asset_name`, `offset`, `size`, `decoded_size`, `codec` e `metadata` devem ser gerados e validados;
|
||||
- quais invariantes o runtime pode assumir sobre ordenacao, alinhamento, identidade e compatibilidade dos assets;
|
||||
- o que pertence ao contrato do packer vs o que pertence ao `shipper`.
|
||||
|
||||
Sem essa decisao:
|
||||
|
||||
- `assets.pa` corre o risco de virar artefato acidental em vez de contrato;
|
||||
- o `shipper` nao tem base normativa para montar `.pmc` de forma deterministica;
|
||||
- specs de asset continuam descrevendo so consumo, nao producao;
|
||||
- tooling pode introduzir heuristica local para ids, offsets, metadata e codecs.
|
||||
|
||||
## Pontos Criticos
|
||||
|
||||
### Fatos
|
||||
|
||||
- o runtime atual consome `asset_table` + `assets.pa`, nao uma API do packer;
|
||||
- `AssetEntry` hoje exige `asset_id`, `asset_name`, `bank_type`, `offset`, `size`, `decoded_size`, `codec` e `metadata`;
|
||||
- o loader atual so carrega cart em formato de diretorio; `.pmc` ainda nao esta implementado;
|
||||
- o runtime hoje aceita apenas `RAW` para `TILES` e `SOUNDS`;
|
||||
- o decode atual depende de metadata especifica por bank:
|
||||
- `TILES`: `tile_size`, `width`, `height`;
|
||||
- `SOUNDS`: `sample_rate` opcional, com default.
|
||||
|
||||
### Riscos
|
||||
|
||||
- deixar `asset_id` ou ordenacao dependentes de detalhes de filesystem;
|
||||
- acoplar o formato interno de `assets.pa` ao container `.pmc`;
|
||||
- permitir metadata insuficiente ou ambigua e empurrar validacao para o runtime;
|
||||
- introduzir codec/versionamento sem registry ou politica de compatibilidade;
|
||||
- permitir que packer e shipper dupliquem responsabilidade sobre manifest e tabela de assets.
|
||||
|
||||
### Tradeoffs
|
||||
|
||||
- packer minimalista e simples agora vs contrato mais rigido e extensivel depois;
|
||||
- `asset_id` derivado automaticamente vs declarado/estavel;
|
||||
- blob puro com offsets vs envelope com header interno proprio;
|
||||
- metadata livre em JSON vs schema normativo por `bank_type` e `codec`;
|
||||
- validacao forte no packer vs tolerancia maior no runtime.
|
||||
|
||||
### Hipoteses
|
||||
|
||||
- o `shipper` deve tratar `asset_table` + `assets.pa` como output fechado do packer, sem reinterpretar layout interno;
|
||||
- o packer deve produzir resultado deterministico para a mesma entrada;
|
||||
- a compatibilidade futura de codecs fica melhor se a facing do packer declarar registry e schema desde o inicio.
|
||||
|
||||
## Opcoes
|
||||
|
||||
### Opcao 1 - Packer como gerador de blob opaco + tabela
|
||||
|
||||
O packer recebe fontes de asset, decide ids/layout e entrega:
|
||||
|
||||
- `assets.pa`;
|
||||
- `asset_table`;
|
||||
- eventualmente um relatorio de build nao normativo.
|
||||
|
||||
Vantagens:
|
||||
|
||||
- encaixa direto no runtime atual;
|
||||
- separa bem packer de shipper;
|
||||
- reduz trabalho inicial.
|
||||
|
||||
Desvantagens:
|
||||
|
||||
- pode esconder heuristicas importantes dentro do tooling;
|
||||
- tende a deixar `asset_id` e metadata sem contrato claro.
|
||||
|
||||
### Opcao 2 - Packer com manifest proprio normativo
|
||||
|
||||
O packer recebe uma spec de entrada dedicada de assets e produz uma saida formal com:
|
||||
|
||||
- `assets.pa`;
|
||||
- `asset_table`;
|
||||
- manifesto/intermediate proprio do packer.
|
||||
|
||||
Vantagens:
|
||||
|
||||
- deixa ownership editorial mais claro;
|
||||
- facilita reproducibilidade e testes de golden output;
|
||||
- prepara evolucao de codecs e validadores.
|
||||
|
||||
Desvantagens:
|
||||
|
||||
- aumenta escopo antes de fechar o minimo necessario;
|
||||
- corre risco de criar artefato intermediario normativo demais cedo.
|
||||
|
||||
### Opcao 3 - Packer como biblioteca interna do shipper
|
||||
|
||||
O packer nao ganha fronteira propria; o shipper absorve a logica de assets e so expomos o contrato final do cart.
|
||||
|
||||
Vantagens:
|
||||
|
||||
- menos moving parts no curto prazo.
|
||||
|
||||
Desvantagens:
|
||||
|
||||
- conflita com a separacao conceitual desejada;
|
||||
- embaralha discussao de `assets.pa` com `.pmc`;
|
||||
- dificulta testes focados na superficie de assets.
|
||||
|
||||
## Sugestao / Recomendacao
|
||||
|
||||
Fechar o packer como produtor normativo de `asset_table` + `assets.pa`, com fronteira propria e independente do `shipper`.
|
||||
|
||||
Recomendacao objetiva para avancar:
|
||||
|
||||
1. O contrato do packer deve ser definido em torno da saida observavel consumida pelo runtime, nao em torno do `.pmc`.
|
||||
2. O `shipper` deve consumir o output do packer como artefato fechado e so cuidar de empacotar o cart final.
|
||||
3. O v1 do packer deve assumir:
|
||||
- `assets.pa` como blob sequencial deterministico;
|
||||
- `asset_table` como mapa normativo da segmentacao do blob;
|
||||
- registry inicial de codecs/banks suportados pelo runtime atual;
|
||||
- schema minimo de metadata por combinacao `bank_type` + `codec`.
|
||||
4. A decisao precisa fixar explicitamente:
|
||||
- estrategia de `asset_id`;
|
||||
- ordenacao canonica dos assets no blob;
|
||||
- regras de alinhamento, se existirem;
|
||||
- politica para duplicatas de nome;
|
||||
- responsabilidades de validacao entre packer e runtime.
|
||||
|
||||
Essa direcao reduz ambiguidade sem antecipar o design completo do `shipper`.
|
||||
|
||||
## Perguntas em Aberto
|
||||
|
||||
1. Qual e a entrada canonica do packer: arquivos soltos, manifesto de assets, API de biblioteca, ou combinacao?
|
||||
2. `asset_id` precisa ser estavel entre builds identicos e entre reorganizacoes de input?
|
||||
3. O packer deve ordenar assets por declaracao, por nome, por bank, ou por politica explicita de layout?
|
||||
4. `assets.pa` continua sendo blob puro sem header proprio ou o packer deve ter envelope/versionamento interno?
|
||||
5. Qual e o schema normativo minimo de `metadata` por tipo de asset no v1?
|
||||
6. O v1 deve aceitar so `RAW` ou ja reservar namespace/registry para codecs futuros?
|
||||
7. Quem rejeita inconsistencias de `decoded_size`, metadata faltante e offset invalido: packer, shipper, runtime, ou todos em camadas diferentes?
|
||||
8. Preload pertence ao dominio do packer, do shipper, ou apenas do cart manifest?
|
||||
|
||||
## Criterio para Encerrar
|
||||
|
||||
Esta agenda pode virar `decision` quando houver definicao escrita de:
|
||||
|
||||
- fronteira formal entre `packer` e `shipper`;
|
||||
- input e output canonicos do packer;
|
||||
- contrato normativo de producao de `asset_table` e `assets.pa`;
|
||||
- politica de identidade, ordenacao e layout dos assets no blob;
|
||||
- schema minimo de metadata e registry inicial de codecs/banks;
|
||||
- matriz de validacao e erro entre packer, shipper e runtime;
|
||||
- estrategia de teste de compatibilidade entre output do packer e consumo do runtime.
|
||||
|
||||
## Referencias
|
||||
|
||||
- `../specs/13-cartridge.md`
|
||||
- `../specs/15-asset-management.md`
|
||||
- `008-packed-cartridge-loader-pmc.md`
|
||||
- `../../crates/console/prometeu-hal/src/asset.rs`
|
||||
- `../../crates/console/prometeu-drivers/src/asset.rs`
|
||||
@ -24,7 +24,6 @@ As agendas atuais são:
|
||||
- `020-perf-host-debug-overlay-isolation.md`
|
||||
- `021-perf-vm-allocation-and-copy-pressure.md`
|
||||
- `022-perf-cartridge-boot-and-program-ownership.md`
|
||||
- `023-asset-packer-runtime-facing-contract.md`
|
||||
|
||||
## Sequenciamento Recomendado [PERF]
|
||||
|
||||
@ -57,10 +56,9 @@ Ordem sugerida para discussão e futura execução:
|
||||
1. `012-vm-owned-random-service.md`
|
||||
2. `014-app-home-filesystem-surface-and-semantics.md`
|
||||
3. `007-runtime-edge-test-plan.md`
|
||||
4. `023-asset-packer-runtime-facing-contract.md`
|
||||
5. `008-packed-cartridge-loader-pmc.md`
|
||||
6. `009-system-run-cart.md`
|
||||
7. `010-system-fault-semantics-and-control-surface.md`
|
||||
4. `008-packed-cartridge-loader-pmc.md`
|
||||
5. `009-system-run-cart.md`
|
||||
6. `010-system-fault-semantics-and-control-surface.md`
|
||||
|
||||
Justificativa curta:
|
||||
|
||||
@ -69,12 +67,11 @@ Justificativa curta:
|
||||
- `013` foi fechada e absorvida por `spec 08` (historico em `learn/historical-game-memcard-slots-surface-and-semantics.md`).
|
||||
- `014` fecha o contrato de `home` para apps sem abrir FS global.
|
||||
- a decisao `007` fixa o nucleo de fault policy de `fs`; os detalhes ficam distribuidos entre `spec 08` (`game`) e agenda `014` (`app`).
|
||||
- `023` separa o contrato de producao de `assets.pa` do contrato de shipping do `.pmc`.
|
||||
- a decisao `008` fixa o contrato status-first de `gfx`.
|
||||
- a decisao `009` fixa o contrato status-first de `audio`.
|
||||
- a decisao `010` fixa o contrato status-first de `asset`.
|
||||
- a agenda `007` vem depois para transformar as decisoes em cobertura de regressao na borda do runtime.
|
||||
- `008` depende de `023`, porque o `shipper` do `.pmc` nao deve decidir o contrato interno do packer de assets no meio da implementacao.
|
||||
- `008` depende da decisao `011`, porque o `shipper` do `.pmc` nao deve decidir o contrato interno do packer de assets no meio da implementacao.
|
||||
- `009` e `010` ficam no fim porque `run_cart` nao e objetivo do ciclo atual.
|
||||
|
||||
Dependências principais:
|
||||
@ -82,8 +79,7 @@ Dependências principais:
|
||||
- `012` depende da decisao `006` e de `16`/`16a`
|
||||
- `014` depende das decisoes `003`/`007`, de `16a`, de `12` (Hub/OS) e de `13` (`app_mode`)
|
||||
- `007` depende da estabilizacao minima das agendas de superficie/fault por dominio
|
||||
- `023` depende do contrato atual de `13-cartridge.md`/`15-asset-management.md` e deve cristalizar a superficie produtora de `asset_table` + `assets.pa`
|
||||
- `008` depende de `023`, de contrato fechado de `13-cartridge.md` e de comportamento equivalente ao loader de diretorio
|
||||
- `008` depende da decisao `011`, de contrato fechado de `13-cartridge.md` e de comportamento equivalente ao loader de diretorio
|
||||
- `009` depende da decisao `003`, de `16a` e da decisao `006`, e deve alinhar com `spec 08`/agenda `014` quando usar `fs`
|
||||
- `010` depende de `16a` e da `009`
|
||||
|
||||
|
||||
@ -0,0 +1,253 @@
|
||||
# Decision Record - `assets.pa` Autocontained Runtime Contract
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Contexto
|
||||
|
||||
A agenda `023-asset-packer-runtime-facing-contract.md` existia para fechar a fronteira runtime-facing do packer de assets sem misturar essa discussao com o `shipper` do `.pmc`.
|
||||
|
||||
O ponto de partida atual do runtime ainda e fragmentado:
|
||||
|
||||
- `manifest.json` carrega `asset_table` e `preload`;
|
||||
- `assets.pa` contem apenas os bytes packed de payload;
|
||||
- o loader le `assets.pa` inteiro para memoria;
|
||||
- o `AssetManager` mantem esse blob inteiro residente.
|
||||
|
||||
Ao mesmo tempo, a direcao desejada para o projeto ja esta clara:
|
||||
|
||||
- o `packer` continua responsavel por produzir o artefato de assets;
|
||||
- o `shipper` continua responsavel por publicar `manifest.json` e montar o cart final;
|
||||
- o runtime deve consumir um `assets.pa` autocontido;
|
||||
- `asset_table`, `preload` e payload mantem o mesmo conteudo semantico atual;
|
||||
- o que muda e onde esses artefatos vivem e como o runtime os carrega.
|
||||
|
||||
O alvo de hardware do PROMETEU e um handheld de baixo custo. Portanto, manter o blob inteiro de assets em RAM como regra geral nao e um baseline aceitavel.
|
||||
|
||||
## Decisao
|
||||
|
||||
### 1. `assets.pa` passa a ser o contrato runtime-facing de assets
|
||||
|
||||
O contrato primario de assets consumido pelo runtime passa a ser o proprio `assets.pa`.
|
||||
|
||||
`manifest.json` deixa de ser a superficie primaria para:
|
||||
|
||||
- `asset_table`;
|
||||
- `preload`.
|
||||
|
||||
O runtime continua agnostico a como o `packer` e o `shipper` produzem artefatos auxiliares.
|
||||
|
||||
### 2. `assets.pa` v1 e um binario autocontido
|
||||
|
||||
`assets.pa` v1 deve ser estruturado como:
|
||||
|
||||
```text
|
||||
[prelude binario fixo]
|
||||
[header JSON]
|
||||
[payload binario]
|
||||
```
|
||||
|
||||
O prelude binario fixo v1 contem, no minimo:
|
||||
|
||||
- `magic`
|
||||
- `schema_version`
|
||||
- `header_len`
|
||||
- `payload_offset`
|
||||
|
||||
Campos opcionais permitidos no prelude v1:
|
||||
|
||||
- `flags`
|
||||
- `reserved`
|
||||
- `header_checksum`
|
||||
|
||||
### 3. O header JSON carrega `asset_table` e `preload`
|
||||
|
||||
O header JSON de `assets.pa` e a estrutura que carrega:
|
||||
|
||||
- `asset_table`
|
||||
- `preload`
|
||||
|
||||
Essa decisao nao redefine o conteudo semantico dessas estruturas.
|
||||
|
||||
Portanto:
|
||||
|
||||
- `AssetEntry` permanece a fonte de verdade para identidade, codec, metadata e offsets;
|
||||
- `PreloadEntry` permanece um insumo de boot;
|
||||
- o payload packed continua representando os bytes frios dos assets.
|
||||
|
||||
### 4. Offsets da `asset_table` sao relativos ao payload
|
||||
|
||||
Os `offset`s de `asset_table` permanecem relativos ao inicio da regiao de payload, nao ao inicio do arquivo inteiro.
|
||||
|
||||
Isso preserva a semantica atual do runtime e evita contaminar `AssetEntry` com detalhes do envelope externo.
|
||||
|
||||
O runtime resolve cada slice como:
|
||||
|
||||
```text
|
||||
payload_base + entry.offset
|
||||
```
|
||||
|
||||
### 5. Lifecycle de `preload` e `asset_table` no runtime
|
||||
|
||||
O runtime deve tratar essas duas estruturas de forma diferente:
|
||||
|
||||
- `preload` e dado transitorio de boot;
|
||||
- `asset_table` e a fonte da verdade para resolucao e carregamento de assets.
|
||||
|
||||
Contrato operacional:
|
||||
|
||||
1. o runtime materializa `manifest.json`;
|
||||
2. se `Capability::Asset` estiver presente, o runtime exige `assets.pa` valido imediatamente;
|
||||
3. o runtime abre `assets.pa`, le o prelude e o header JSON;
|
||||
4. o runtime materializa `asset_table` em memoria;
|
||||
5. o runtime usa `preload` na fase de boot;
|
||||
6. apos o boot, `preload` pode ser descartado;
|
||||
7. `asset_table` permanece viva enquanto o cart estiver rodando.
|
||||
|
||||
### 6. Falha antecipada quando `Capability::Asset` exigir `assets.pa`
|
||||
|
||||
Cart sem `assets.pa` continuam validos.
|
||||
|
||||
Mas, se o `manifest.json` declarar `Capability::Asset`, a ausencia de `assets.pa` deve falhar o mais cedo possivel, antes da fase de preload.
|
||||
|
||||
Essa falha pertence ao bootstrap do cart, nao ao lifecycle de `asset.load`.
|
||||
|
||||
### 7. Leitura de payload deve ser sob demanda
|
||||
|
||||
O runtime nao deve manter o payload inteiro de `assets.pa` residente em memoria como comportamento baseline.
|
||||
|
||||
O contrato de leitura do runtime passa a ser baseado em uma primitiva equivalente a:
|
||||
|
||||
```text
|
||||
open_slice(offset, size)
|
||||
```
|
||||
|
||||
Essa primitiva abre uma view limitada para um asset dentro da regiao de payload.
|
||||
|
||||
### 8. Pipeline canonico de carregamento de asset
|
||||
|
||||
O caminho canonico de carregamento passa a ser:
|
||||
|
||||
```text
|
||||
ROM -> open_slice -> CODEX/decode -> Bank
|
||||
```
|
||||
|
||||
ou, quando o CODEX exigir materializacao temporaria:
|
||||
|
||||
```text
|
||||
ROM -> open_slice -> blob temporario em memoria -> CODEX/decode -> Bank
|
||||
```
|
||||
|
||||
O runtime nunca deve materializar o `assets.pa` inteiro apenas para suportar carregamento de asset.
|
||||
|
||||
### 9. `OP_MODE` de consumo do payload
|
||||
|
||||
O runtime deve encapsular o modo operacional de consumo do payload por asset.
|
||||
|
||||
Esse `OP_MODE` escolhe entre:
|
||||
|
||||
- leitura direta da ROM via view limitada;
|
||||
- materializacao temporaria do slice em memoria.
|
||||
|
||||
Direcao v1:
|
||||
|
||||
- o `OP_MODE` e derivado do `codec`/CODEX por padrao;
|
||||
- hint explicito adicional so deve ser introduzido se algum codec real admitir mais de um modo operacional viavel.
|
||||
|
||||
### 10. Artefatos auxiliares do packer continuam permitidos
|
||||
|
||||
O `packer` pode continuar emitindo artefatos auxiliares para o `shipper`, por exemplo:
|
||||
|
||||
- `asset_table.json`;
|
||||
- relatorios de build;
|
||||
- hashes;
|
||||
- inventarios.
|
||||
|
||||
Mas esses artefatos:
|
||||
|
||||
- sao derivados;
|
||||
- nao substituem o header interno de `assets.pa`;
|
||||
- nao definem o contrato runtime-facing.
|
||||
|
||||
## Rationale
|
||||
|
||||
Esta decisao fecha a ambiguidade central da agenda `023` sem reabrir a semantica do dominio `asset`.
|
||||
|
||||
Ela foi escolhida porque:
|
||||
|
||||
- separa claramente `packer` e `shipper`;
|
||||
- reduz dependencia de metadata de asset espalhada em `manifest.json`;
|
||||
- preserva o shape semantico atual de `asset_table`, `preload` e payload;
|
||||
- melhora a adequacao do runtime para hardware barato;
|
||||
- evita carregar o blob inteiro em RAM;
|
||||
- permite que codecs com diferentes necessidades de IO operem sobre a mesma fronteira de leitura.
|
||||
|
||||
O uso de prelude binario pequeno + header JSON foi adotado porque:
|
||||
|
||||
- permite localizar o header com custo fixo;
|
||||
- mantem o header facil de produzir, inspecionar e depurar;
|
||||
- evita transformar o payload em estrutura textual;
|
||||
- reduz complexidade editorial no v1.
|
||||
|
||||
## Invariantes / Contrato
|
||||
|
||||
- `assets.pa` e o contrato runtime-facing de assets.
|
||||
- `asset_table` e `preload` deixam de ser contrato primario de runtime no `manifest.json`.
|
||||
- `asset_table` e carregada do header de `assets.pa` e permanece viva durante toda a execucao do cart.
|
||||
- `preload` e carregado do header de `assets.pa`, usado no boot e descartavel apos a inicializacao.
|
||||
- payload offsets em `AssetEntry` sao relativos ao inicio da regiao de payload.
|
||||
- o runtime deve falhar cedo se `Capability::Asset` exigir `assets.pa` e o artefato nao existir.
|
||||
- o runtime nao deve manter o `assets.pa` inteiro em RAM como baseline.
|
||||
- o runtime deve expor leitura sob demanda por slice.
|
||||
- `OP_MODE` de consumo do slice e resolvido pelo runtime a partir do `codec`/CODEX, salvo decisao futura em contrario.
|
||||
- auxiliares do `packer` para o `shipper` nao tem autoridade normativa sobre o runtime.
|
||||
|
||||
## Impactos
|
||||
|
||||
### Specs
|
||||
|
||||
- `13-cartridge.md` deve mover `asset_table` e `preload` para dentro do contrato de `assets.pa`.
|
||||
- `15-asset-management.md` deve descrever `assets.pa` como artefato autocontido, separar lifecycle de `preload` e `asset_table`, e registrar offsets relativos ao payload.
|
||||
- `16-host-abi-and-syscalls.md` so precisa ser tocada se a superficie host/runtime de inicializacao de assets mudar de forma observavel.
|
||||
|
||||
### Runtime
|
||||
|
||||
- `cartridge_loader.rs` deve deixar de ler `assets.pa` inteiro para `Vec<u8>` como baseline.
|
||||
- `cartridge.rs` deve parar de tratar `asset_table` e `preload` como dados vindos do `manifest`.
|
||||
- o bootstrap deve checar cedo a presenca de `assets.pa` quando `Capability::Asset` estiver declarada.
|
||||
- o `AssetManager` deve manter `asset_table` viva, aplicar `preload` no boot e ler payload por slice sob demanda.
|
||||
- a leitura atual baseada em `Arc<RwLock<Vec<u8>>>` deve evoluir para uma origem de leitura por ROM/view/slice.
|
||||
|
||||
### Shipper / Packer
|
||||
|
||||
- o `packer` deve produzir `assets.pa` com prelude + header JSON + payload.
|
||||
- o `shipper` continua livre para consumir auxiliares JSON, mas deve tratar `assets.pa` como artefato de verdade para assets.
|
||||
- o `manifest.json` publicado pelo `shipper` deixa de carregar `asset_table` e `preload` como contrato primario de runtime.
|
||||
|
||||
### Firmware / Boot
|
||||
|
||||
- a etapa de carga do cart deve abrir `assets.pa`, extrair header e decidir falha cedo antes de preload.
|
||||
- preload deixa de ser atributo editorial do manifest e passa a ser insumo interno do artefato de assets.
|
||||
|
||||
## Referencias
|
||||
|
||||
- `../specs/13-cartridge.md`
|
||||
- `../specs/15-asset-management.md`
|
||||
- `../agendas/008-packed-cartridge-loader-pmc.md`
|
||||
- `../../../studio/docs/packer/Prometeu Packer.md`
|
||||
- `../../crates/console/prometeu-hal/src/cartridge_loader.rs`
|
||||
- `../../crates/console/prometeu-hal/src/cartridge.rs`
|
||||
- `../../crates/console/prometeu-drivers/src/asset.rs`
|
||||
|
||||
## Propagacao Necessaria
|
||||
|
||||
- criar PR/plan para atualizar specs `13` e `15`;
|
||||
- criar PR/plan de codigo para:
|
||||
- mudar o loader de cart para abrir header de `assets.pa`;
|
||||
- mover `asset_table`/`preload` para a leitura do binario de assets;
|
||||
- introduzir leitura sob demanda por slice;
|
||||
- remover o baseline de payload inteiro residente;
|
||||
- falhar cedo quando `Capability::Asset` exigir `assets.pa` ausente;
|
||||
- agenda `023-asset-packer-runtime-facing-contract.md` deve ser considerada fechada e removida da lista de agendas ativas;
|
||||
- agenda `008-packed-cartridge-loader-pmc.md` passa a depender desta decisao como base do artefato de assets.
|
||||
@ -19,6 +19,7 @@ Decisoes ativas:
|
||||
- `003-vm-owned-byte-transfer-protocol.md`
|
||||
- `006-vm-owned-stateful-core-contract.md`
|
||||
- `007-filesystem-fault-core-policy.md`
|
||||
- `011-assets-pa-autocontained-runtime-contract.md`
|
||||
|
||||
Decisoes implementadas e aposentadas (migradas para `learn/`):
|
||||
|
||||
|
||||
@ -0,0 +1,93 @@
|
||||
# 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.
|
||||
@ -0,0 +1,76 @@
|
||||
# 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.
|
||||
@ -0,0 +1,60 @@
|
||||
# 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.
|
||||
@ -0,0 +1,70 @@
|
||||
# PR - Asset Manager On-Demand Payload and OP_MODE
|
||||
|
||||
## Briefing
|
||||
|
||||
Com bootstrap e `open_slice` ja estabilizados, o `AssetManager` pode ser migrado do modelo atual baseado em blob inteiro residente para o modelo decidido na `011`:
|
||||
|
||||
- `asset_table` viva durante toda a execucao;
|
||||
- `preload` apenas no boot;
|
||||
- payload lido sob demanda;
|
||||
- pipeline `ROM -> open_slice -> CODEX/decode -> Bank` ou `ROM -> open_slice -> blob temporario -> CODEX/decode -> Bank`.
|
||||
|
||||
Esta PR implementa a mudanca de comportamento interno do `AssetManager` sem reabrir o envelope de `assets.pa`.
|
||||
|
||||
## Decisions de Origem
|
||||
|
||||
- `../decisions/011-assets-pa-autocontained-runtime-contract.md`
|
||||
|
||||
## Alvo
|
||||
|
||||
Refatorar o `AssetManager` para consumir payload sob demanda e encapsular `OP_MODE` por codec/CODEX.
|
||||
|
||||
## Escopo
|
||||
|
||||
- remover o baseline de `Arc<RwLock<Vec<u8>>>` para payload inteiro residente;
|
||||
- fazer `AssetManager` depender de `asset_table` viva + origem de payload por slice;
|
||||
- tratar `preload` apenas na inicializacao;
|
||||
- encapsular `OP_MODE` por codec/CODEX;
|
||||
- suportar:
|
||||
- leitura direta da ROM via slice;
|
||||
- materializacao temporaria em memoria quando o codec exigir;
|
||||
- preservar a superficie observavel do dominio `asset`.
|
||||
|
||||
## Fora de Escopo
|
||||
|
||||
- redefinir envelope de `assets.pa`;
|
||||
- `.pmc`;
|
||||
- novos codecs;
|
||||
- rediscutir a policy de `asset` syscall status-first.
|
||||
|
||||
## Plano de Execucao
|
||||
|
||||
1. Substituir `assets_data` por origem de payload em slices.
|
||||
2. Adaptar preload para usar a nova origem de payload apenas durante o boot.
|
||||
3. Adaptar `load()` e o caminho assíncrono para consumir slices sob demanda.
|
||||
4. Introduzir `OP_MODE` derivado de `codec`/CODEX.
|
||||
5. Garantir que o resultado continue indo para staging/resident/bank como hoje.
|
||||
|
||||
## Criterios de Aceite
|
||||
|
||||
- `AssetManager` nao depende mais de payload inteiro residente em RAM.
|
||||
- preload usa a nova origem de payload e nao permanece vivo depois do boot.
|
||||
- `asset_table` continua sendo a fonte da verdade para resolucao de asset.
|
||||
- `asset.load/status/commit/cancel` preservam a superficie observavel atual.
|
||||
- o pipeline para decode/bank suporta leitura direta ou blob temporario conforme o `OP_MODE`.
|
||||
|
||||
## Tests / Validacao
|
||||
|
||||
- testes de `AssetManager` para:
|
||||
- preload no boot;
|
||||
- leitura por offsets relativos ao payload;
|
||||
- ausencia de dependencia em blob inteiro residente;
|
||||
- path de leitura direta;
|
||||
- path de blob temporario;
|
||||
- smoke tests de `asset.load/status/commit/cancel` para garantir ausencia de regressao observavel.
|
||||
|
||||
## Riscos
|
||||
|
||||
- regressao de preload ao trocar a origem do payload;
|
||||
- encapsulamento ruim entre source/view, codec e bank;
|
||||
- reintroduzir copia excessiva por atalho local no caminho assíncrono.
|
||||
@ -37,3 +37,16 @@ Uma PR deste diretório deve:
|
||||
## Roadmap Publicado
|
||||
|
||||
PRs propostas para execucao da rodada atual:
|
||||
|
||||
- `PR-011a-assets-pa-autocontained-spec-propagation.md`
|
||||
- origem: decisao `011-assets-pa-autocontained-runtime-contract.md`
|
||||
- alvo: consolidar o contrato runtime-facing em `spec 13` e `spec 15`
|
||||
- `PR-011b-assets-pa-bootstrap-and-header-loading.md`
|
||||
- origem: decisao `011-assets-pa-autocontained-runtime-contract.md`
|
||||
- alvo: implementar bootstrap, parse do header e falha antecipada por capability
|
||||
- `PR-011c-assets-pa-payload-source-and-open-slice.md`
|
||||
- origem: decisao `011-assets-pa-autocontained-runtime-contract.md`
|
||||
- alvo: introduzir a origem de payload e `open_slice`
|
||||
- `PR-011d-asset-manager-on-demand-payload-and-op-mode.md`
|
||||
- origem: decisao `011-assets-pa-autocontained-runtime-contract.md`
|
||||
- alvo: migrar o `AssetManager` para payload sob demanda e `OP_MODE`
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user