2.3 KiB
| id | ticket | title | created | tags | |||||
|---|---|---|---|---|---|---|---|---|---|
| LSN-0056 | corrigir-identificacao-formato-pbx | Runtime Artifact Identity Must Not Borrow Frontend Names | 2026-07-15 |
|
Context
Prometeu accepts bytecode produced by multiple frontends. PBS is the base frontend language, while PBX is the executable bytecode artifact consumed by the runtime.
The runtime had inherited PBS terminology in the executable bytecode path, including the serialized magic number, comments, tests, and VM loader checks. That made one frontend appear to own the runtime executable format.
Key Decisions
PBX Executable Format Identity
What: PBX is the runtime executable bytecode format, and PBX\0 is its only
valid magic number.
Why: Runtime artifact identity must be independent from any frontend that can produce the artifact. Naming the executable format after PBS would make the runtime boundary look language-specific.
Trade-offs: The correction intentionally rejects old PBS-prefixed executable artifacts instead of carrying a compatibility alias. This keeps the format contract singular, but requires stale generated fixtures to be regenerated or updated.
Patterns and Algorithms
Put file-format identity in the module that serializes and deserializes the format. Loaders and higher-level runtime code should call that boundary instead of duplicating magic-number checks.
When renaming an artifact identity, update all fixture construction and generator assertions in the same pass as production serialization. Mixed fixture identity usually means tests are asserting historical spelling rather than current contract.
Pitfalls
Do not globally erase frontend names. PBS remains correct when the subject is the PBS language, stdlib, or frontend-facing API. It is wrong only when it names the executable bytecode artifact.
Do not preserve old magic values just to make a rename feel less disruptive. If there is no compatibility requirement for old artifacts, aliases keep the incorrect model alive.
Takeaways
- Runtime artifact names should describe the runtime contract, not the compiler or frontend that produced the artifact.
- Magic numbers are normative format identity, not cosmetic labels.
- Loader code should delegate file-format validation to the format owner.