--- id: AGD-0051 ticket: corrigir-identificacao-formato-pbx title: Corrigir Identificacao do Formato PBX status: in_progress created: 2026-07-15 resolved: 2026-07-15 decision: DEC-0042 tags: [runtime, bytecode, pbx, loader, format, architecture] --- ## Contexto O formato executavel do Prometeu deve ser identificado como PBX, Prometeu Bytecode Executable. Esse nome representa o artefato binario carregado e executado pelo runtime, independentemente da linguagem ou frontend que gerou o programa. Hoje ainda existem referencias a PBS no caminho do bytecode executavel. A busca inicial encontrou `PBS\0` no encoder/decoder de `prometeu-bytecode`, verificacoes diretas no loader da VM, comentarios sobre "PBS format" e testes que constroem imagens usando `PBS\0`. Esse estado cria uma associacao indevida entre o formato executavel e o frontend PBS. A direcao desejada e tratar PBX como contrato do runtime e deixar PBS como uma possivel linguagem de origem, nao como identidade do binario. ## Problema O runtime aceita e produz imagens com magic number `PBS\0`, embora o contrato conceitual do executavel seja PBX. Alem disso, a verificacao do magic aparece em mais de um lugar, o que cria risco de divergencia entre o modulo responsavel pelo formato binario e o loader da VM. A correcao precisa decidir: - onde o magic number canonico deve viver; - se a transicao deve aceitar apenas `PBX\0` ou preservar algum modo legado temporario; - quais comentarios, nomes de teste e mensagens de erro devem ser renomeados; - qual camada deve validar o formato e qual camada deve apenas consumir o resultado decodificado. ## Pontos Criticos - **Fato:** `crates/console/prometeu-bytecode/src/model.rs` escreve e valida `PBS\0` diretamente. - **Fato:** `crates/console/prometeu-vm/src/virtual_machine/loader.rs` tambem testa `program_bytes.starts_with(b"PBS\0")`. - **Fato:** testes em `prometeu-vm`, `prometeu-bytecode`, `prometeu-layer-tests` e `pbxgen-dummy-boy` ainda citam PBS ou constroem headers com `PBS\0`. - **Fato:** a documentacao de arquitetura e ISA ja usa PBX para o artefato de bytecode em pontos relevantes. - **Risco:** aceitar `PBS\0` e `PBX\0` indefinidamente manteria dois contratos de arquivo para o mesmo formato. - **Risco:** trocar apenas strings e testes, sem centralizar o magic, pode deixar a duplicacao no loader pronta para regressao futura. - **Hipotese:** como os cartuchos de teste sao gerados por ferramentas locais (`pbxgen-*`) e nao ha compromisso declarado com executaveis antigos, a mudanca pode ser estrita para `PBX\0`. ## Opcoes ### Opcao A - Renomeacao estrita para PBX com magic centralizado - **Abordagem:** definir uma constante publica do formato binario, por exemplo `PBX_MAGIC: [u8; 4] = *b"PBX\0"`, no crate/modulo dono da serializacao PBX; fazer encoder, decoder, geradores e testes usarem essa constante; remover do loader da VM a verificacao duplicada por magic e deixar o decoder retornar `InvalidFormat`. - **Pro:** fecha o contrato com uma unica identidade de arquivo; elimina a associacao PBS no runtime; reduz duplicidade no loader. - **Contra:** qualquer artefato antigo com `PBS\0` deixa de carregar e precisa ser regenerado. - **Manutenibilidade:** melhor opcao no longo prazo porque o formato fica nomeado no ponto certo e o loader nao precisa conhecer bytes de cabecalho. ### Opcao B - Aceitar `PBS\0` como alias legado durante uma janela de transicao - **Abordagem:** introduzir `PBX\0` como magic canonico, mas permitir que o decoder aceite `PBS\0` temporariamente, possivelmente emitindo erro, aviso ou marcador de compatibilidade. - **Pro:** reduz quebra imediata se houver artefatos binarios preexistentes fora dos testes. - **Contra:** prolonga a existencia de dois magic numbers validos e exige uma politica clara para remover o alias. - **Manutenibilidade:** aceitavel apenas se houver necessidade real de compatibilidade; sem data de remocao, vira divida permanente. ### Opcao C - Renomear comentarios/testes, mas manter o magic atual - **Abordagem:** trocar nomenclatura superficial de PBS para PBX em comentarios e nomes de teste, sem alterar o magic number nem a validacao duplicada. - **Pro:** menor alteracao imediata. - **Contra:** conserva o erro principal no contrato de arquivo e mascara a discrepancia entre nome e bytes reais. - **Manutenibilidade:** fraca; aumenta a chance de futuras decisoes assumirem que PBX ja esta corrigido quando o magic ainda nao foi corrigido. ## Sugestao / Recomendacao Seguir a Opcao A, salvo evidencia concreta de que precisamos carregar executaveis antigos com `PBS\0`. A decisao deveria fixar que: - PBX e o nome do formato executavel do runtime; - o magic canonico e `PBX\0`; - a constante do magic pertence ao modulo/crate responsavel pela serializacao do formato binario; - o loader da VM nao deve duplicar a verificacao de magic, apenas chamar o decoder/linker apropriado e propagar erro de formato; - referencias a PBS devem permanecer apenas quando o assunto for explicitamente a linguagem/frontend PBS, nao o executavel. ## Perguntas em Aberto - [x] Existe algum artefato binario `PBS\0` publicado ou preservado que precise continuar carregando? - Nao. A correcao deve ser sem compatibilidade legada para `PBS\0`. - [x] O erro de formato deve mencionar explicitamente `PBX\0` ou apenas "invalid PBX magic"? - A decisao deve preservar o estilo atual de erro quando possivel; o ponto essencial e trocar a identidade do formato para PBX, nao redesenhar a semantica de diagnostico. - [x] A constante do magic deve ficar em `prometeu-bytecode::model`, em um modulo dedicado de formato, ou em uma API publica do crate para ser consumida por geradores e testes? - Nao ha necessidade de redesenhar a organizacao atual do formato. A mudanca deve seguir a mesma estrutura que hoje trata o magic como PBS, corrigindo a identidade para PBX e centralizando o literal no modulo responsavel pelo formato binario. - [x] A especificacao canonica do formato PBX ja existe em `docs/specs`, ou esta agenda deve originar tambem uma decisao/plano para adicionar esse trecho? - Sim, a execucao deve atualizar a especificacao canonica em `docs/specs` para registrar PBX como formato executavel do runtime e `PBX\0` como magic number. ## Criterio para Encerrar Encerrar esta agenda quando houver acordo sobre: - aceitar apenas `PBX\0` ou manter alias temporario para `PBS\0`; - o ponto canonico da constante do magic; - a responsabilidade do loader da VM; - o escopo de renomeacao em comentarios, testes, geradores e documentacao. Com essas respostas, a agenda esta pronta para virar uma decisao normativa e depois um plano de execucao para specs e codigo. ## Discussion Aberta em 2026-07-15 a partir do pedido para corrigir a identificacao do formato PBX e remover referencias indevidas a PBS no runtime. 2026-07-15: Fechado entendimento de que nao havera compatibilidade com `PBS\0`. A mudanca deve corrigir a identidade do formato de PBS para PBX dentro da organizacao atual do crate de bytecode, evitando redesenho desnecessario. O problema central e separar o frontend PBS do bytecode executavel PBX, ja que o Prometeu aceita multiplos frontends. A execucao deve incluir atualizacao em `docs/specs`. ## Resolution A agenda recomenda decisao normativa com os seguintes pontos: - PBX e o formato executavel do runtime, independente do frontend de origem. - O magic number canonico passa a ser `PBX\0`. - Nao deve haver alias legado para `PBS\0`. - A implementacao deve seguir a organizacao atual do crate de bytecode, apenas corrigindo a identidade e centralizando o magic no modulo responsavel pelo formato binario. - O loader da VM nao deve manter verificacao duplicada do magic quando a validacao pertence ao decoder/modelo do formato. - A especificacao canonica em `docs/specs` deve registrar o contrato PBX.