# 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`