prometeu-runtime/discussion/workflow/decisions/DEC-0042-pbx-executable-format-identity.md

id	ticket	title	status	created	accepted	agenda	plans	tags
DEC-0042	corrigir-identificacao-formato-pbx	PBX Executable Format Identity	accepted	2026-07-15	2026-07-15	AGD-0051	PLN-0173	runtime bytecode pbx loader format architecture

Status

Accepted.

Contexto

Prometeu supports multiple frontends. PBS is the base Prometeu frontend language, but it is not the identity of the runtime executable artifact.

The runtime executable bytecode format is PBX, Prometeu Bytecode Executable. Current runtime code still carries the wrong PBS identity in the executable bytecode path, including the serialized magic number PBS\0, comments, tests, and a duplicated VM loader check.

That naming leak binds the runtime bytecode format to one frontend and weakens the boundary between frontend language output and runtime executable input.

Decisao

PBX SHALL be the canonical identity of the Prometeu runtime executable bytecode format.

The canonical PBX magic number MUST be PBX\0.

The runtime MUST NOT accept PBS\0 as a legacy alias for PBX. Existing generated artifacts or tests that use PBS\0 MUST be regenerated or updated to PBX\0.

The implementation MUST preserve the current bytecode crate organization unless a local code constraint forces a narrower mechanical adjustment. This decision does not authorize a format-module redesign.

The magic literal MUST be centralized in the module that owns binary bytecode serialization/deserialization. Encoder, decoder, tests, and local PBX generators SHOULD consume that central definition where the existing crate boundaries allow it.

The VM loader MUST NOT duplicate PBX magic validation when that validation belongs to the bytecode decoder/model layer. The loader SHOULD delegate bytecode format recognition to the bytecode crate and propagate the resulting format error.

References to PBS MUST remain only where the subject is the PBS frontend language or its frontend-facing API. References to the executable bytecode artifact MUST use PBX.

The canonical runtime specs under docs/specs MUST record PBX as the executable bytecode format and PBX\0 as its magic number.

Rationale

PBS and PBX name different layers.

PBS is a frontend language. PBX is the runtime executable artifact. Since Prometeu accepts multiple frontends, naming the executable format as PBS incorrectly implies that the runtime bytecode is tied to the base frontend.

Rejecting legacy PBS\0 keeps the file contract singular. Supporting both PBS\0 and PBX\0 would preserve the same ambiguity this decision is meant to remove.

Keeping the current bytecode crate organization limits the change to contract correction and mechanical propagation. The problem is the wrong identity, not the module layout.

Centralizing the magic number at the bytecode serialization boundary prevents the VM loader, tests, and generators from becoming independent sources of truth for the executable format.

Invariantes / Contrato

• PBX is the runtime executable bytecode format.
• PBS is not the runtime executable bytecode format.
• PBX\0 is the only valid magic number for PBX artifacts.
• PBS\0 is invalid as a PBX artifact magic number.
• PBX magic validation belongs to the bytecode format layer.
• VM loader code must not own a separate PBX magic check.
• Tests must express PBX fixture data with the same identity used by production bytecode serialization.
• Runtime specs must describe the PBX executable identity in English.

Technical Specification

The execution plan derived from this decision must update at least these surfaces when present:

• bytecode serialization and deserialization code that writes or validates PBS\0;
• bytecode comments and type documentation that describe the executable format as PBS;
• VM loader logic that checks program_bytes.starts_with(b"PBS\0");
• tests that construct bytecode headers with PBS\0;
• local PBX generator tests that assert a PBS\0 prefix;
• layer tests or diagnostics that describe invalid executable bytes as PBS-specific;
• runtime specs under docs/specs that need an explicit PBX executable format contract.

The execution plan must avoid broad redesign. A small public constant, local constant, or existing-module export is acceptable if it follows the current bytecode crate structure.

Constraints

• No compatibility alias for PBS\0.
• No new binary format versioning policy is introduced by this decision.
• No frontend language behavior is changed by this decision.
• No cartridge container magic such as PMTU is changed by this decision.
• No asset payload magic values are changed by this decision.
• No loader ownership expansion is allowed; loader responsibility should shrink where duplicate format validation exists.

Impactos

• Spec: docs/specs must state PBX executable identity and magic number in English.
• Runtime: bytecode encoder/decoder and VM loader behavior must converge on PBX\0.
• Host: no direct host behavior change is expected.
• Firmware: no direct firmware behavior change is expected unless firmware tests or generated cartridges embed PBX bytes.
• Tooling: local PBX generators and tests must emit/assert PBX\0.
• Tests: invalid-format and loader-hardening tests must be renamed or adjusted so PBS remains frontend terminology only.

Referencias

• AGD-0051: discussion/workflow/agendas/AGD-0051-corrigir-identificacao-formato-pbx.md
• crates/console/prometeu-bytecode/src/model.rs
• crates/console/prometeu-vm/src/virtual_machine/loader.rs
• docs/specs

Propagacao Necessaria

• Create an execution plan before editing specs or code.
• Update runtime specs before or alongside code execution.
• Update code and tests in the same implementation pass so no mixed PBS\0/PBX\0 state remains.
• After execution, create or update lesson material only if the implementation reveals a reusable boundary lesson beyond this decision.

Revision Log

• 2026-07-15: Initial draft from AGD-0051.
• 2026-07-15: Accepted by user and linked to PLN-0173.