# 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.

```text
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.