From 683d291afd709a9f17a73dde57465822b0c0573e Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Wed, 11 Mar 2026 05:45:30 +0000 Subject: [PATCH] added packer agenda --- ...23-asset-packer-runtime-facing-contract.md | 181 ++++++++++++++++++ docs/runtime/agendas/README.md | 14 +- 2 files changed, 190 insertions(+), 5 deletions(-) create mode 100644 docs/runtime/agendas/023-asset-packer-runtime-facing-contract.md diff --git a/docs/runtime/agendas/023-asset-packer-runtime-facing-contract.md b/docs/runtime/agendas/023-asset-packer-runtime-facing-contract.md new file mode 100644 index 00000000..90ddcd6c --- /dev/null +++ b/docs/runtime/agendas/023-asset-packer-runtime-facing-contract.md @@ -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` diff --git a/docs/runtime/agendas/README.md b/docs/runtime/agendas/README.md index 9cf520ec..af975264 100644 --- a/docs/runtime/agendas/README.md +++ b/docs/runtime/agendas/README.md @@ -24,6 +24,7 @@ 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] @@ -56,9 +57,10 @@ 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. `008-packed-cartridge-loader-pmc.md` -5. `009-system-run-cart.md` -6. `010-system-fault-semantics-and-control-surface.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` 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`). - `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` 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. Dependências principais: @@ -79,7 +82,8 @@ 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 -- `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` - `010` depende de `16a` e da `009`