prometeu-runtime/docs/runtime/agendas/002-packed-cartridge-loader-pmc.md

Agenda - Packed Cartridge Loader PMC

Problema

O loader reconhece a extensão .pmc, mas o caminho empacotado ainda nao existe de verdade.

Hoje o dispatcher aceita a intenção e delega para um loader que sempre falha com InvalidFormat.

Dor

• A plataforma declara dois formatos de entrada, mas só um funciona.
• Distribuição real de cartuchos fica travada no layout de diretório.
• Host, firmware e ferramentas nao conseguem validar o caminho de distribuição final.
• O runtime continua dependente de estrutura de workspace em vez de artefato fechado.

Alvo da Discussao

Definir o formato e o contrato do cartucho empacotado .pmc como artefato de distribuição do runtime.

O objetivo nao é só "descompactar um zip", e sim fixar:

• layout interno;
• regras de validação;
• limites de compatibilidade;
• superfície de erro;
• impacto em assinatura/versionamento futuro.

O Que Precisa Ser Definido

1. Container. O .pmc é zip, tar, formato próprio, ou envelope simples com header e blobs?

2. Estrutura interna. Quais arquivos são obrigatórios e opcionais:

   • manifest.json
   • program.pbx
   • assets.pa
   • outros metadados

3. Regras de validação. Ordem de parsing, integridade, presença de arquivos, tamanho máximo, duplicatas e versão suportada.

4. Política de compatibilidade. Como o loader reage a versões futuras do container e do manifesto.

5. Segurança e determinismo. Como impedir traversal, nomes ambíguos, arquivos extras maliciosos e dependência da ordem física do container.

6. Relação com o loader de diretório. O comportamento validado deve ser idêntico entre diretório e .pmc, mudando apenas a origem dos bytes.

O Que Necessita Para Resolver

• especificação mínima do container .pmc;
• decisão sobre biblioteca/abordagem de parsing;
• matriz de erros determinísticos;
• testes com cartuchos sintéticos válidos e inválidos;
• garantia de equivalência comportamental com o loader de diretório.

Fora de Escopo

• compressão otimizada;
• assinatura criptográfica;
• distribuição incremental;
• pipeline completo do builder/packer.

Critério de Saida Desta Agenda

Pode virar PR quando houver definição escrita de:

• formato do .pmc;
• arquivos obrigatórios;
• erros canônicos;
• invariantes de segurança;
• estratégia de testes de compatibilidade entre diretório e pacote.