prometeu-runtime/discussion/workflow/plans/PLN-0173-pbx-executable-format-identity.md

id	ticket	title	status	created	completed	decisions	tags
PLN-0173	corrigir-identificacao-formato-pbx	PBX Executable Format Identity Implementation	review	2026-07-15		DEC-0042	runtime bytecode pbx loader format tests specs

Briefing

Implement DEC-0042 by correcting the Prometeu runtime executable bytecode identity from PBS to PBX.

The executable bytecode format must use PBX\0 as its only valid magic number. PBS\0 must not remain accepted as an alias. PBS references must remain only when they refer to the PBS frontend language or frontend-facing APIs.

Decisions de Origem

• DEC-0042 - PBX Executable Format Identity

Alvo

After execution, runtime bytecode serialization, runtime bytecode deserialization, loader behavior, local PBX generators, tests, and runtime specs must agree that:

• PBX is the runtime executable bytecode format.
• PBX\0 is the only valid PBX magic number.
• PBS\0 is invalid executable bytecode magic.
• VM loader code does not own a separate magic-number gate.

Escopo

Included

• Add or expose a canonical PBX magic constant in the existing prometeu-bytecode format ownership path.
• Replace bytecode serialization and deserialization use of PBS\0 with PBX\0.
• Remove duplicate VM loader magic validation that currently checks program_bytes.starts_with(b"PBS\0").
• Update tests that construct executable bytecode headers with PBS\0.
• Update local PBX generator tests that assert the old magic prefix.
• Rename executable-format comments and diagnostics that incorrectly call the executable image PBS.
• Add or update English runtime specs under docs/specs to record PBX executable identity and PBX\0.

Excluded

• No compatibility path for PBS\0.
• No new binary format versioning policy.
• No redesign of the bytecode crate module layout.
• No frontend language behavior changes.
• No changes to cartridge container magic such as PMTU.
• No changes to asset payload magic values.
• No broad cleanup of legitimate PBS frontend references in specs.

Fora de Escopo

• Reworking PBX instruction encoding.
• Reworking syscall binding, SYSC, HOSTCALL, or verifier behavior except where tests depend on the corrected magic.
• Moving bytecode model types into new modules.
• Introducing migration tooling for old PBS\0 artifacts.

Plano de Execucao

Step 1 - Accept the decision in discussion metadata

What: Mark DEC-0042 as accepted and link this plan to it.

How: Update the decision frontmatter and discussion/index.ndjson so the decision is accepted, the discussion is ready for planning, and PLN-0173 is linked through ref_decisions.

File(s):

• discussion/workflow/decisions/DEC-0042-pbx-executable-format-identity.md
• discussion/index.ndjson

Step 2 - Centralize PBX magic in the bytecode format owner

What: Define the canonical PBX magic as PBX\0 in the current bytecode model/serialization area.

How: Add a constant in crates/console/prometeu-bytecode/src/model.rs or the nearest existing module that already owns binary bytecode serialization. Use the current organization; do not create a new format subsystem.

File(s):

• crates/console/prometeu-bytecode/src/model.rs

Step 3 - Update bytecode serialization and deserialization

What: Make the bytecode crate write and validate PBX\0.

How: Replace direct b"PBS\0" writes and comparisons with the centralized PBX magic constant. Update comments that describe the magic and executable image as PBS. Keep current error shape unless the code already names the format in the message.

File(s):

• crates/console/prometeu-bytecode/src/model.rs
• crates/console/prometeu-bytecode/src/program_image.rs

Step 4 - Remove duplicate VM loader magic ownership

What: Stop the VM loader from performing a separate magic-number gate.

How: Remove the program_bytes.starts_with(b"PBS\0") branch from crates/console/prometeu-vm/src/virtual_machine/loader.rs. Let the bytecode decoder/model validate the executable format and propagate invalid-format failure. Preserve existing loader behavior for successful PBX artifacts and for invalid bytes.

File(s):

• crates/console/prometeu-vm/src/virtual_machine/loader.rs

Step 5 - Update VM and bytecode tests

What: Align all executable bytecode fixtures with PBX.

How: Replace test headers that copy b"PBS\0" with the PBX magic constant when crate boundaries allow it, or with b"PBX\0" when importing the constant would add inappropriate coupling. Rename comments/test data that call executable images PBS.

File(s):

• crates/console/prometeu-vm/src/virtual_machine.rs
• crates/console/prometeu-bytecode/src/model.rs
• crates/dev/prometeu-layer-tests/tests/verifier_closure_reject.rs

Step 6 - Update local PBX generator assertions

What: Ensure generated cartridges/programs assert PBX executable magic.

How: Change pbxgen-dummy-boy tests that currently assert bytes.starts_with(b"PBS\0") to assert PBX\0, preferably using the bytecode crate constant if it is already accessible to the tool crate.

File(s):

• crates/tools/pbxgen-dummy-boy/src/lib.rs

Step 7 - Update runtime specs

What: Record PBX executable identity and magic number in canonical runtime specs.

How: Add a concise English contract section in the most appropriate docs/specs/runtime document. The section must state that PBX is the runtime executable bytecode format, PBX\0 is the only valid magic, and PBS is a frontend name rather than executable-format identity. Do not remove legitimate references to PBS frontend APIs.

File(s):

• docs/specs/runtime/16-host-abi-and-syscalls.md if the PBX pre-load artifact contract is the best local home.
• Another existing docs/specs/runtime/*.md file only if inspection shows a more direct bytecode/executable-format location.

Step 8 - Verify no mixed executable identity remains

What: Ensure the repository no longer contains executable-format PBS\0 or PBS image wording.

How: Run literal searches for PBS\0, NOT_PBS_IMAGE, and executable-format PBS comments. Keep PBS mentions that clearly refer to the frontend language or frontend-facing APIs.

File(s):

• crates/
• docs/specs/
• docs/vm-arch/

Criterios de Aceite

• prometeu-bytecode writes PBX\0 for executable bytecode artifacts.
• prometeu-bytecode rejects PBS\0 as invalid executable magic.
• The PBX magic literal is centralized in the existing bytecode format ownership path.
• VM loader code no longer checks program_bytes.starts_with(b"PBS\0") or owns any replacement magic check.
• Tests and local generators no longer construct or assert executable artifacts with PBS\0.
• Legitimate PBS references remain only for the PBS frontend language or frontend-facing APIs.
• docs/specs states the PBX executable identity and PBX\0 magic contract in English.
• Repository search finds no PBS\0 occurrences after execution.

Tests / Validacao

Unit Tests

• Run the bytecode crate tests that cover serialization/deserialization and invalid magic behavior.
• Run VM loader tests that cover invalid format and loader hardening.
• Run pbxgen-dummy-boy tests that assert generated executable bytes.

Integration Tests

• Run the layer test containing verifier_closure_reject after renaming the invalid image fixture.
• Run broader workspace tests if local execution time is acceptable after the targeted tests pass.

Manual Verification

• rg -n -F "PBS\\0" crates docs/specs docs/vm-arch must return no results.
• rg -n -F "NOT_PBS_IMAGE" crates docs/specs docs/vm-arch must return no results.
• rg -n -F "PBS" crates docs/specs docs/vm-arch must show only frontend-language or frontend-facing references.
• discussion validate must pass after plan creation and after implementation updates.

Dependencies

• DEC-0042 must remain accepted before execution starts.
• Existing bytecode crate boundaries must be respected; imports of the PBX magic constant into tools/tests must not create inappropriate dependency cycles.
• The runtime spec location should be chosen from existing docs/specs/runtime structure before editing.

Riscos

• Importing the PBX magic constant into all tests may create unwanted crate dependencies; use direct b"PBX\0" in tests where that is the least coupled option.
• Removing the loader magic gate may expose assumptions in loader tests that expected early rejection before decoding; update tests to assert behavior, not internal rejection site.
• Broad PBS search results include legitimate frontend references; execution must not erase frontend terminology from specs or APIs.
• If generated test cartridges are checked in elsewhere, they must be regenerated or updated in the same implementation pass.