added packer agenda
This commit is contained in:
parent
9c5c1df394
commit
683d291afd
SSH Key Fingerprint:
SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
181
docs/runtime/agendas/023-asset-packer-runtime-facing-contract.md
Normal file
181
docs/runtime/agendas/023-asset-packer-runtime-facing-contract.md
Normal file
@ -0,0 +1,181 @@
|
|||||||
|
# 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,6 +24,7 @@ As agendas atuais são:
|
|||||||
- `020-perf-host-debug-overlay-isolation.md`
|
- `020-perf-host-debug-overlay-isolation.md`
|
||||||
- `021-perf-vm-allocation-and-copy-pressure.md`
|
- `021-perf-vm-allocation-and-copy-pressure.md`
|
||||||
- `022-perf-cartridge-boot-and-program-ownership.md`
|
- `022-perf-cartridge-boot-and-program-ownership.md`
|
||||||
|
- `023-asset-packer-runtime-facing-contract.md`
|
||||||
|
|
||||||
## Sequenciamento Recomendado [PERF]
|
## Sequenciamento Recomendado [PERF]
|
||||||
|
|
||||||
@ -56,9 +57,10 @@ Ordem sugerida para discussão e futura execução:
|
|||||||
1. `012-vm-owned-random-service.md`
|
1. `012-vm-owned-random-service.md`
|
||||||
2. `014-app-home-filesystem-surface-and-semantics.md`
|
2. `014-app-home-filesystem-surface-and-semantics.md`
|
||||||
3. `007-runtime-edge-test-plan.md`
|
3. `007-runtime-edge-test-plan.md`
|
||||||
4. `008-packed-cartridge-loader-pmc.md`
|
4. `023-asset-packer-runtime-facing-contract.md`
|
||||||
5. `009-system-run-cart.md`
|
5. `008-packed-cartridge-loader-pmc.md`
|
||||||
6. `010-system-fault-semantics-and-control-surface.md`
|
6. `009-system-run-cart.md`
|
||||||
|
7. `010-system-fault-semantics-and-control-surface.md`
|
||||||
|
|
||||||
Justificativa curta:
|
Justificativa curta:
|
||||||
|
|
||||||
@ -67,11 +69,12 @@ Justificativa curta:
|
|||||||
- `013` foi fechada e absorvida por `spec 08` (historico em `learn/historical-game-memcard-slots-surface-and-semantics.md`).
|
- `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.
|
- `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`).
|
- 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 `008` fixa o contrato status-first de `gfx`.
|
||||||
- a decisao `009` fixa o contrato status-first de `audio`.
|
- a decisao `009` fixa o contrato status-first de `audio`.
|
||||||
- a decisao `010` fixa o contrato status-first de `asset`.
|
- 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.
|
- a agenda `007` vem depois para transformar as decisoes em cobertura de regressao na borda do runtime.
|
||||||
- `008` e importante, mas nao bloqueia bytecode/backend agora.
|
- `008` depende de `023`, 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.
|
- `009` e `010` ficam no fim porque `run_cart` nao e objetivo do ciclo atual.
|
||||||
|
|
||||||
Dependências principais:
|
Dependências principais:
|
||||||
@ -79,7 +82,8 @@ Dependências principais:
|
|||||||
- `012` depende da decisao `006` e de `16`/`16a`
|
- `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`)
|
- `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
|
- `007` depende da estabilizacao minima das agendas de superficie/fault por dominio
|
||||||
- `008` depende de contrato fechado de `13-cartridge.md` + comportamento equivalente ao loader de diretorio
|
- `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
|
||||||
- `009` depende da decisao `003`, de `16a` e da decisao `006`, e deve alinhar com `spec 08`/agenda `014` quando usar `fs`
|
- `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`
|
- `010` depende de `16a` e da `009`
|
||||||
|
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user