prometeu-runtime/docs/runtime/agendas/023-asset-packer-runtime-facing-contract.md

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