This commit is contained in:
Nilton Constantino
2026-01-31 20:39:05 +00:00
parent 83e24920b4
commit ff4dcad5dc
42 changed files with 2941 additions and 603 deletions
@@ -0,0 +1,167 @@
# 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.
@@ -1388,6 +1388,23 @@ This avoids overloading the meaning of `TypeName.member`.
### 8.7 Summary of Struct Rules
Full example of `struct`:
```pbs
declare struct Vector(x: float, y: float)
[
(): (0.0, 0.0) as default { }
(a: float): (a, a) as square { }
]
[[
ZERO: default()
]]
{
pub fn len(self: this): float { ... }
pub fn scale(self: mut this): void { ... }
}
```
* Structs are declared with `declare struct`.
* Fields are private and cannot be accessed directly.
* Constructor aliases exist only inside the type and are called as `Type.alias(...)`.
-17
View File
@@ -20,23 +20,6 @@
---
## PR-13 — Optional: Refactor Value representation (tagged slots) for clarity
**Why:** If current `Value` representation is the source of complexity/bugs, refactor now.
### Scope (only if needed)
* Make `Slot` explicit:
* `Slot::I32`, `Slot::I64`, `Slot::U32`, `Slot::Bool`, `Slot::ConstId`, `Slot::GateId`, `Slot::Unit`
* Multi-slot types become sequences of slots.
### Acceptance
* Simpler, more verifiable runtime.
---
## Definition of Done (DoD) for PBS v0 “minimum executable”
A single canonical cartridge runs end-to-end: