fix PBX executable format identity
This commit is contained in:
@@ -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.
|
||||
Reference in New Issue
Block a user