prometeu-runtime/docs/specs/pbs/PBS - Module and Linking Model.md

PBS v0 — Module & Linking Model (Self‑Contained Blob)

Status

Accepted (v0) — This specification defines the authoritative execution and linking model for PBS v0.

---

1. Motivation

PBS is designed to be executed by a small, deterministic virtual machine embedded in PrometeuOS. To keep the VM simple, secure, and optimizable, all semantic linking must happen before runtime, in the compiler/tooling layer.

The VM is not a linker. It is an executor with validation guarantees.

---

2. Core Principle

A PBS module must be fully self‑contained and executable as a single blob.

There is no runtime linking in PBS v0.

The VM only performs:

load → verify → execute

---

3. What “Linking” Means in PBS

In PBS, linking refers to resolving all symbolic or relative references into a final, index‑based layout.

This includes:

• Function call resolution
• Control‑flow targets (JMP / conditional branches)
• Constant pool indexing
• Syscall signature binding

All of this must be fully resolved by the compiler/toolchain.

---

4. PBS v0 Module Structure

A PBS v0 module consists of:

• code: [u8] — final bytecode stream
• functions: [FunctionMeta] — function table
• const_pool: [Const] — constant pool
• (optional) metadata (build id, debug info, hashes)

The module is self‑contained: no external symbols, imports, or relocations.

---

5. Function Table and CALL Semantics

5.1 Function Identification

Functions are identified by index in the function table.

CALL <u32 func_id>

There are no address‑based calls in PBS v0.

5.2 FunctionMeta

Each function is described by FunctionMeta:

• code_offset
• code_len
• param_slots
• local_slots
• return_slots
• (optional) max_stack_slots (precomputed)

The compiler is responsible for emitting correct metadata.

---

6. Control Flow (JMP / Branches)

• All jump targets are relative to the start of the current function.
• Targets must land on valid instruction boundaries.

This eliminates the need for global relocations.

---

7. Role of the Compiler / Tooling

The compiler (or offline tooling) is responsible for:

• Resolving all calls to func_id
• Emitting the final function table
• Laying out code contiguously
• Emitting valid jump targets
• Computing stack effects (optionally embedding max_stack_slots)
• Ensuring ABI‑correct syscall usage

The output must be a ready‑to‑run PBS module.

---

8. Role of the VM

The VM does not perform linking.

It is responsible for:

• Parsing the module
• Verifying structural and semantic correctness
• Executing bytecode deterministically

8.1 Mandatory Runtime Verification

The VM must always verify:

• Bytecode truncation / corruption
• Stack underflow / overflow
• Invalid func_id
• Invalid jump targets
• Syscall signature mismatches

These checks exist for safety and determinism, not for late binding.

---

9. Legacy and Compatibility Policies

Legacy formats (e.g. PPBC) may be supported behind explicit policies.

Example:

• Legacy CALL addr encodings are rejected under Policy (A)
• Only CALL func_id is valid in PBS v0

Compatibility handling is orthogonal to the linking model.

---

10. Future Evolution (Non‑Goals for v0)

PBS v0 explicitly does not define:

• Multi‑module linking
• Dynamic imports
• Runtime symbol resolution
• Relocation tables

These may appear in future versions (v1+), but v0 is closed and static by design.

---

11. Summary

• PBS modules are single, self‑contained blobs
• All linking happens before runtime
• The VM is a verifying executor, not a linker
• This model enables aggressive optimization, predictability, and simplicity

This specification is normative for PBS v0.