clean up
This commit is contained in:
parent
0553b3927e
commit
f3f689fbef
SSH Key Fingerprint:
SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
@ -1,93 +0,0 @@
|
||||
# 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.
|
||||
@ -1,76 +0,0 @@
|
||||
# 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.
|
||||
@ -1,60 +0,0 @@
|
||||
# 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.
|
||||
@ -1,70 +0,0 @@
|
||||
# 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.
|
||||
@ -38,15 +38,3 @@ Uma PR deste diretório deve:
|
||||
|
||||
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