192 lines
8.7 KiB
Markdown
192 lines
8.7 KiB
Markdown
---
|
|
id: PLN-0173
|
|
ticket: corrigir-identificacao-formato-pbx
|
|
title: PBX Executable Format Identity Implementation
|
|
status: review
|
|
created: 2026-07-15
|
|
completed:
|
|
decisions: [DEC-0042]
|
|
tags: [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.
|