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
-
Container. O
.pmcé zip, tar, formato próprio, ou envelope simples com header e blobs? -
Estrutura interna. Quais arquivos são obrigatórios e opcionais:
manifest.jsonprogram.pbxassets.pa- outros metadados
-
Regras de validação. Ordem de parsing, integridade, presença de arquivos, tamanho máximo, duplicatas e versão suportada.
-
Política de compatibilidade. Como o loader reage a versões futuras do container e do manifesto.
-
Segurança e determinismo. Como impedir traversal, nomes ambíguos, arquivos extras maliciosos e dependência da ordem física do container.
-
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
.pmcpara qualquer host que useCartridgeLoader, incluindo o host desktop e o host headless deAGD-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
.pmcexistir, 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
InvalidFormatgenérico do stub?