prometeu-runtime/discussion/workflow/agendas/AGD-0051-corrigir-identificacao-formato-pbx.md

id	ticket	title	status	created	resolved	decision	tags
AGD-0051	corrigir-identificacao-formato-pbx	Corrigir Identificacao do Formato PBX	in_progress	2026-07-15	2026-07-15	DEC-0042	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

• Existe algum artefato binario PBS\0 publicado ou preservado que precise continuar carregando?
  • Nao. A correcao deve ser sem compatibilidade legada para PBS\0.
• 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.
• 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.
• 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.