added packer agenda

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`

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`