fix PBX executable format identity

This commit is contained in:
2026-07-15 08:01:47 +01:00
parent b2d2533acb
commit f0f3f972ce
13 changed files with 113 additions and 461 deletions
@@ -1,113 +0,0 @@
---
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.