Files
prometeu-studio/docs/specs/compiler/15. Bytecode and PBX Mapping Specification.md
T
bquarkz ea1cc26fe3
Test / Tests and coverage occurred while executing withChecks step.
Intrepid/Prometeu/Studio/pipeline/pr-master There was a failure building this commit
feat(studio): improve compiler reliability and AI diagnostics
Preserve structured diagnostics, source attribution, phase outcomes and revision context through compiler, Studio, LSP, MCP and JavaFX. Add project service discovery and resilient VS Code reconnection.

Correct all eight reproduced PBS production failures in expression context, sibling executable bindings and nominal owner identity. Consolidate specs, lessons, immutable baseline evidence and the maintained source-to-guest qualification runner.

Validation: required Gradle gate recorded 724 tests, with 711 passed and 13 skipped. Full corpus passed 168 compilation observations and 108 guest runs (104 successes and four deliberate faults); supplemental controls passed 42 compilations and 16 guest runs. TypeScript compilation, two Node discovery tests and discussion validation passed.
2026-11-10 12:36:25 +00:00

213 lines
8.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Bytecode and PBX Mapping Specification
The current typed Registry/PBX v0 contract is normative in
[Typed common Registry and PBX v0](25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md).
Its complete typed function records, mandatory sections and verification rules
replace the earlier slot-only artifact baseline.
Status: Draft v1 (Backend Baseline)
Applies to: mapping from lowered/optimized backend programs into PBX sections, bytecode-facing artifacts, and source-to-artifact invariants required by loader/verifier/runtime
## 1. Purpose
This document defines the normative mapping between backend-lowered semantics and emitted PBX/bytecode-facing artifacts.
Its purpose is to keep artifact emission deterministic and compatible with runtime loader/verifier contracts.
PBX is the only executable boundary between the compiler and runtime. `IRVM`
is a compiler-internal representation consumed by bytecode emission; it MUST
NOT be exposed to or consumed by the runtime loader, verifier, or PVM.
## 2. Scope
This document defines:
- artifact-level obligations at `IRVM -> BytecodeModule` emission boundary,
- mapping invariants for function layout, code layout, callsite forms, and host-binding declarations,
- minimum debug/source-attribution hooks for v1 backend/runtime diagnostics and conformance,
- and deterministic artifact rejection expectations for emitter-side failures.
This document does not define:
- full ISA semantics,
- runtime loader patching internals,
- or one mandatory emitter implementation architecture.
## 3. Authority and Precedence
Normative precedence:
1. Runtime authority ([provider specifications](../../../../runtime/docs/specs/runtime/README.md); [mirror and provenance policy](../../vm-arch/README.md))
2. Bytecode authority ([provider Core ISA](../../../../runtime/docs/vm-arch/ISA_CORE.md))
3. `docs/specs/compiler-languages/pbs/6.1. Intrinsics and Builtin Types Specification.md`
4. `docs/specs/compiler-languages/pbs/6.2. Host ABI Binding and Loader Resolution Specification.md`
5. `20. IRBackend to IRVM Lowering Specification.md`
6. `21. IRVM Optimization Pipeline Specification.md`
7. This document
If a rule here conflicts with higher-precedence authorities, it is invalid.
## 4. Normative Inputs
This document depends on, at minimum:
- `docs/specs/compiler-languages/pbs/6.1. Intrinsics and Builtin Types Specification.md`
- `docs/specs/compiler-languages/pbs/6.2. Host ABI Binding and Loader Resolution Specification.md`
- `20. IRBackend to IRVM Lowering Specification.md`
- `21. IRVM Optimization Pipeline Specification.md`
## 5. Already-Settled Inputs
The following are fixed and must not be contradicted:
- The compiler emits host-binding declarations in PBX `SYSC`.
- Host-backed callsites are emitted in pre-load form as `HOSTCALL <sysc_index>`.
- `SYSC` entries are deduplicated by canonical identity and ordered by first occurrence.
- The loader resolves host bindings and rewrites `HOSTCALL` to `SYSCALL` before execution.
- Raw `SYSCALL` in pre-load artifacts is rejected.
- VM-owned intrinsic artifacts are distinct from `SYSC`, `HOSTCALL`, and `SYSCALL`.
- `SYSC` section is mandatory in valid PBX artifacts (empty section is valid).
## 6. Artifact Mapping Contract (v1)
### 6.1 Required module surfaces
Emitter output must map to a `BytecodeModule` shape containing:
1. `const_pool`,
2. `functions`,
3. `code`,
4. `exports`,
5. `syscalls`,
6. typed Registry declarations, implementations and per-function capture lists,
7. optional `debug_info` that still satisfies v1 minimum debug obligations.
### 6.2 Function ordering and IDs
Function ordering must be deterministic:
1. the published wrapper function index is `0`,
2. function index `0` is owned by the compiler-selected physical wrapper rather than by manifest metadata or nominal export lookup,
3. remaining functions are ordered by `(moduleId -> modulePool canonical key, callable_name, source_start)`,
4. identical admitted input graph yields identical function ordering and function ids.
For PBS executable publication:
- the userland callable marked with `[Frame]` is not itself the physical entrypoint unless it is wrapped by the published synthetic wrapper,
- final `FRAME_RET` belongs to the wrapper path.
### 6.3 Function code layout
Emitter must satisfy:
1. `code_offset` values are unique and monotonic over function order,
2. `code_len` exactly matches emitted bytes for each function body,
3. `code_offset + code_len` stays within `code.len`,
4. and final code concatenation is deterministic.
### 6.4 Instruction encoding
Emitter must satisfy:
1. little-endian encoding,
2. instruction layout `[opcode: u16][immediate]`,
3. jump immediates as `u32` offsets relative to function start,
4. immediate sizes matching selected Core ISA opcode spec.
### 6.5 Host-backed mapping obligations
For host-backed operations:
1. emit canonical declarations in `SYSC` (`module`, `name`, `version`, `arg_slots`, `ret_slots`),
2. deduplicate by canonical identity,
3. order by first occurrence,
4. emit callsites as `HOSTCALL <sysc_index>` only,
5. do not emit raw `SYSCALL` in pre-load artifact form.
### 6.6 VM-owned intrinsic mapping obligations
For VM-owned intrinsic operations:
1. emit VM-owned intrinsic call form (`INTRINSIC <id>`),
2. resolve `<id>` from the canonical ISA-scoped intrinsic registry artifact,
3. keep intrinsic path distinct from host-binding metadata and host call opcodes,
4. and do not emit VM-owned builtin/intrinsic semantics through `SYSC`.
### 6.7 Internal symbolic-to-index mapping
Compilers may use internal symbolic references before final index materialization.
If used, symbolic references must be resolved deterministically to final numeric indices before serialization.
## 7. Minimum Debug Attribution Contract (v1)
For v1 backend/runtime diagnostics and conformance support, emitted artifacts must preserve at minimum:
1. `function_names` entries for all emitted function indices,
2. `pc_to_span` entries for each emitted instruction start PC.
This minimum does not require one universal source-map format.
### 7.1 Compilation attribution before artifact emission
Compiler failures before PBX emission MUST use attribution from the program being
checked. The IRVM function plan associates each instruction with its emission
operation and optional source origin. Lowering and optimization MUST preserve
that association, including recorded generated provenance, when expanding,
removing or rewriting instructions.
An IRVM verification PC is a zero-based byte offset within a function in the
checked program. It MUST be identified as `pcSpace=irvm-function`, `pcUnit=byte`,
and accompanied by the reporting stage and validation point. It is not an emitted
PBX offset or executed runtime PC. A validation after an optimization pass uses
that pass's output, including its remapped instruction boundaries and origins.
These in-memory diagnostics do not change PBX serialization or the minimum debug
hooks above. A missing instruction origin MUST remain explicit; neither a nearby
instruction nor a function's first line supplies an exact fallback. The complete
diagnostic and public-failure contract is defined in
[Compiler 19, sections 12–13](19.%20Verification%20and%20Safety%20Checks%20Specification.md).
## 8. Deterministic Emitter Rejection
Emitter-side rejection must be deterministic for malformed or inconsistent artifact candidates, including at minimum:
1. inconsistent function layout bounds,
2. unresolved symbolic references at serialization boundary,
3. illegal pre-load host call form (`SYSCALL` in pre-load image),
4. duplicate `SYSC` canonical identities,
5. and declared host ABI shape mismatch detectable at compile target metadata line.
## 9. Conformance-Facing Baseline
At minimum, artifact conformance checks should assert:
1. canonical `SYSC` declarations for admitted host-backed operations,
2. deterministic `SYSC` dedup/order,
3. pre-load `HOSTCALL` callsites for host-backed paths,
4. no host-binding leakage for VM-owned intrinsic/builtin operations,
5. minimum debug attribution hooks required by v1,
6. deterministic function ordering and code layout invariants.
## 10. Explicit Deferrals
The following remain deferred:
- richer optional debug/source-map formats,
- and profile-specific binary compatibility policy details beyond current v1 baseline.
## 11. Non-Goals
- Repeating full ISA/runtime documentation.
- Mandating one byte-for-byte whole-image golden as sole conformance oracle.
- Defining loader patching internals already owned elsewhere.
## 12. Exit Criteria
This document is healthy when:
1. artifact mapping obligations are explicit and testable,
2. host-backed and VM-owned emission boundaries are explicit,
3. deterministic ordering/layout rules are explicit,
4. and v1 minimum debug/source attribution contract is explicit.