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

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