116 lines
5.9 KiB
Markdown
116 lines
5.9 KiB
Markdown
---
|
|
id: DEC-0042
|
|
ticket: corrigir-identificacao-formato-pbx
|
|
title: PBX Executable Format Identity
|
|
status: accepted
|
|
created: 2026-07-15
|
|
accepted: 2026-07-15
|
|
agenda: AGD-0051
|
|
plans: [PLN-0173]
|
|
tags: [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.
|