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.
8.7 KiB
Bytecode and PBX Mapping Specification
The current typed Registry/PBX v0 contract is normative in Typed common Registry and PBX v0. 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 -> BytecodeModuleemission 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:
- Runtime authority (provider specifications; mirror and provenance policy)
- Bytecode authority (provider Core ISA)
docs/specs/compiler-languages/pbs/6.1. Intrinsics and Builtin Types Specification.mddocs/specs/compiler-languages/pbs/6.2. Host ABI Binding and Loader Resolution Specification.md20. IRBackend to IRVM Lowering Specification.md21. IRVM Optimization Pipeline Specification.md- 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.mddocs/specs/compiler-languages/pbs/6.2. Host ABI Binding and Loader Resolution Specification.md20. IRBackend to IRVM Lowering Specification.md21. 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>. SYSCentries are deduplicated by canonical identity and ordered by first occurrence.- The loader resolves host bindings and rewrites
HOSTCALLtoSYSCALLbefore execution. - Raw
SYSCALLin pre-load artifacts is rejected. - VM-owned intrinsic artifacts are distinct from
SYSC,HOSTCALL, andSYSCALL. SYSCsection 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:
const_pool,functions,code,exports,syscalls,- typed Registry declarations, implementations and per-function capture lists,
- optional
debug_infothat still satisfies v1 minimum debug obligations.
6.2 Function ordering and IDs
Function ordering must be deterministic:
- the published wrapper function index is
0, - function index
0is owned by the compiler-selected physical wrapper rather than by manifest metadata or nominal export lookup, - remaining functions are ordered by
(moduleId -> modulePool canonical key, callable_name, source_start), - 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_RETbelongs to the wrapper path.
6.3 Function code layout
Emitter must satisfy:
code_offsetvalues are unique and monotonic over function order,code_lenexactly matches emitted bytes for each function body,code_offset + code_lenstays withincode.len,- and final code concatenation is deterministic.
6.4 Instruction encoding
Emitter must satisfy:
- little-endian encoding,
- instruction layout
[opcode: u16][immediate], - jump immediates as
u32offsets relative to function start, - immediate sizes matching selected Core ISA opcode spec.
6.5 Host-backed mapping obligations
For host-backed operations:
- emit canonical declarations in
SYSC(module,name,version,arg_slots,ret_slots), - deduplicate by canonical identity,
- order by first occurrence,
- emit callsites as
HOSTCALL <sysc_index>only, - do not emit raw
SYSCALLin pre-load artifact form.
6.6 VM-owned intrinsic mapping obligations
For VM-owned intrinsic operations:
- emit VM-owned intrinsic call form (
INTRINSIC <id>), - resolve
<id>from the canonical ISA-scoped intrinsic registry artifact, - keep intrinsic path distinct from host-binding metadata and host call opcodes,
- 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:
function_namesentries for all emitted function indices,pc_to_spanentries 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.
8. Deterministic Emitter Rejection
Emitter-side rejection must be deterministic for malformed or inconsistent artifact candidates, including at minimum:
- inconsistent function layout bounds,
- unresolved symbolic references at serialization boundary,
- illegal pre-load host call form (
SYSCALLin pre-load image), - duplicate
SYSCcanonical identities, - and declared host ABI shape mismatch detectable at compile target metadata line.
9. Conformance-Facing Baseline
At minimum, artifact conformance checks should assert:
- canonical
SYSCdeclarations for admitted host-backed operations, - deterministic
SYSCdedup/order, - pre-load
HOSTCALLcallsites for host-backed paths, - no host-binding leakage for VM-owned intrinsic/builtin operations,
- minimum debug attribution hooks required by v1,
- 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:
- artifact mapping obligations are explicit and testable,
- host-backed and VM-owned emission boundaries are explicit,
- deterministic ordering/layout rules are explicit,
- and v1 minimum debug/source attribution contract is explicit.