Files
prometeu-runtime/discussion/workflow/agendas/AGD-0002-packed-cartridge-loader-pmc.md
T
bquarkz e0c08c8b00
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
add headless automation
2026-09-22 13:28:31 +01:00

4.6 KiB

id, ticket, title, status, created, resolved, decision, tags
id ticket title status created resolved decision tags
AGD-0002 packed-cartridge-loader-pmc Agenda - Packed Cartridge Loader PMC open 2026-03-27

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;
  • equivalência observável entre diretório e .pmc para qualquer host que use CartridgeLoader, incluindo o host desktop e o host headless de AGD-0052.

Revalidação — 2026-09-22

Revalidada contra o código atual e contra AGD-0052 / DSC-0049 (Headless Automation Host and Deterministic Runtime Control). A agenda permanece aberta.

O que permanece

PackedCartridgeLoader::load ainda retorna CartridgeError::InvalidFormat sem ler o arquivo. O dispatcher continua aceitando a extensão .pmc e delegando para esse stub. O loader de diretório é o caminho real: manifest.json, program.pbx e assets.pa quando a capability de asset exige. Boot direto (BootTarget::Cartridge) e o host desktop usam esse mesmo CartridgeLoader.

O problema original segue válido: a plataforma anuncia dois formatos e só o diretório funciona.

Efeito da direção headless

AGD-0052 coloca o host headless como consumidor novo do loader, e deixa o formato .pmc fora do primeiro ciclo. O primeiro boot automatizado usa cartucho de diretório, o mesmo artefato que o host desktop já carrega.

Consequências para esta agenda:

  • headless, CI e agente não definem o container;
  • quando .pmc existir, diretório e pacote precisam materializar o mesmo cartucho lógico, para o determinismo não depender da origem dos bytes;
  • a ordem física do container continua impedida de alterar o resultado, como o item de segurança e determinismo já pedia;
  • esta agenda não absorve captura de framebuffer, replay ou protocolo de automação.

O que não mudou no critério

Formato, arquivos obrigatórios, erros canônicos, invariantes de segurança e testes de equivalência continuam sendo o fechamento. O critério de saída ganhou só a exigência de que essa equivalência valha para todo host do CartridgeLoader.

Perguntas que continuam abertas

  • O .pmc é zip, tar, formato próprio ou envelope com header e blobs?
  • Quais entradas são obrigatórias além das que o loader de diretório já exige?
  • Qual matriz de erro determinística substitui o InvalidFormat genérico do stub?