prometeu-studio/docs/specs/random/pbs_old/PBS - Module and Linking Model.md

# Prometeu PBS v0 — Unified Project, Module, Linking & Execution Specification

> **Status:** Canonical / Replaces all previous module & linking specs
>
> This document **fully replaces**:
>
> * "PBS – Module and Linking Model"
> * Any partial or implicit module/linking descriptions in earlier PBS documents
>
> After this document, there must be **no parallel or competing spec** describing project structure, modules, imports, or linking for PBS v0.

---

## 1. Purpose

This specification defines the **single authoritative model** for how a Prometeu PBS v0 program is:

1. Organized as a project
2. Structured into modules
3. Resolved and linked at compile time
4. Emitted as one executable bytecode blob
5. Loaded and executed by the Prometeu Virtual Machine

The primary objective is to **eliminate ambiguity** by enforcing a strict separation of responsibilities:

* **Compiler / Tooling**: all symbolic, structural, and linking work
* **Runtime / VM**: verification and execution only

---

## 2. Core Principles

### 2.1 Compiler Finality Principle

All operations involving **names, symbols, structure, or intent** must be completed at compile time.

The VM **never**:

* Resolves symbols or names
* Loads or links multiple modules
* Applies relocations or fixups
* Interprets imports or dependencies

### 2.2 Single-Blob Execution Principle

A PBS v0 program is executed as **one fully linked, self-contained bytecode blob**.

At runtime there is no concept of:

* Projects
* Modules
* Imports
* Dependencies

These concepts exist **only in the compiler**.

---

## 3. Project Model

### 3.1 Project Root

A Prometeu project is defined by a directory containing:

* `prometeu.json` — project manifest (required)
* One or more module directories

### 3.2 `prometeu.json` Manifest

The project manifest is mandatory and must define:

```json
{
  "name": "example_project",
  "version": "0.1.0",
  "dependencies": {
    "core": "../core",
    "input": "../input"
  }
}
```

#### Fields

* `name` (string, required)

    * Canonical project identifier
* `version` (string, required)
* `dependencies` (map, optional)

    * Key: dependency project name
    * Value: filesystem path or resolver hint

Dependency resolution is **purely a compiler concern**.

---

## 4. Module Model (Compile-Time Only)

### 4.1 Module Definition

* A module is a directory inside a project
* Each module contains one or more `.pbs` source files

### 4.2 Visibility Rules

Visibility is enforced **exclusively at compile time**:

* `file`: visible only within the same source file
* `mod`: visible within the same module
* `pub`: visible to importing modules or projects

The VM has **zero awareness** of visibility.

---

## 5. Imports & Dependency Resolution

### 5.1 Import Syntax

Imports reference **projects and modules**, never files:

```
import @core:math
import @input:pad
```

### 5.2 Resolution Pipeline

The compiler performs the following phases:

1. Project dependency graph resolution (via `prometeu.json`)
2. Module discovery
3. Symbol table construction
4. Name and visibility resolution
5. Type checking

Any failure aborts compilation and **never reaches the VM**.

---

## 6. Linking Model (Compiler Responsibility)

### 6.1 Link Stage

After semantic validation, the compiler executes a **mandatory link stage**.

The linker:

* Assigns final `func_id` indices
* Assigns constant pool indices
* Computes final `code_offset` and `code_len`
* Resolves all jumps and calls
* Merges all module bytecode into one contiguous code segment

### 6.2 Link Output Format

The output of linking is a **Linked PBS Program** with the following layout:

```text
[ Header ]
[ Constant Pool ]
[ Function Table ]
[ Code Segment ]
```

All references are:

* Absolute
* Final
* Fully resolved

No relocations or fixups remain.

---

## 7. Runtime Execution Contract

### 7.1 VM Input Requirements

The Prometeu VM accepts **only linked PBS blobs**.

It assumes:

* All function references are valid
* All jumps target instruction boundaries
* No unresolved imports exist

### 7.2 VM Responsibilities

The VM is responsible for:

1. Loading the bytecode blob
2. Structural and control-flow verification
3. Stack discipline verification
4. Deterministic execution

The VM **must not**:

* Perform linking
* Resolve symbols
* Modify code offsets
* Load multiple modules

---

## 8. Errors and Runtime Traps

### 8.1 Compile-Time Errors

Handled exclusively by the compiler:

* Unresolved imports
* Visibility violations
* Type errors
* Circular dependencies

These errors **never produce bytecode**.

### 8.2 Runtime Traps

Runtime traps represent **deterministic execution faults**, such as:

* Stack underflow
* Invalid local access
* Invalid syscall invocation
* Explicit `TRAP` opcode

Traps are part of the **execution model**, not debugging.

---

## 9. Versioning and Scope

### 9.1 PBS v0 Guarantees

PBS v0 guarantees:

* Single-blob execution
* No runtime linking
* Deterministic behavior

### 9.2 Out of Scope for v0

The following are explicitly excluded from PBS v0:

* Dynamic module loading
* Runtime imports
* Hot reloading
* Partial linking

---

## 10. Canonical Ownership Summary

| Concern           | Owner         |
| ----------------- | ------------- |
| Project structure | Compiler      |
| Dependencies      | Compiler      |
| Modules & imports | Compiler      |
| Linking           | Compiler      |
| Bytecode format   | Bytecode spec |
| Verification      | VM            |
| Execution         | VM            |

> **Rule of thumb:**
> If it requires names, symbols, or intent → compiler.
> If it requires bytes, slots, or PCs → VM.

---

## 11. Final Note

After adoption of this document:

* Any existing or future document describing PBS modules or linking **must defer to this spec**
* Any behavior conflicting with this spec is considered **non-compliant**
* The Prometeu VM is formally defined as a **pure executor**, not a linker

---

## Addendum — `prometeu.json` and Dependency Management

This specification intentionally **does not standardize the full dependency resolution algorithm** for `prometeu.json`.

### Scope Clarification

* `prometeu.json` **defines project identity and declared dependencies only**.
* **Dependency resolution, fetching, version selection, and conflict handling are responsibilities of the Prometeu Compiler**, not the VM and not the runtime bytecode format.
* The Virtual Machine **never reads or interprets `prometeu.json`**.

### Compiler Responsibility

The compiler is responsible for:

* Resolving dependency sources (`path`, `git`, registry, etc.)
* Selecting versions (exact, range, or `latest`)
* Applying aliasing / renaming rules
* Detecting conflicts and incompatibilities
* Producing a **fully linked, closed-world Program Image**

After compilation and linking:

* All symbols are resolved
* All function indices are fixed
* All imports are flattened into the final bytecode image

The VM consumes **only the resulting bytecode blob** and associated metadata.

### Separate Specification

A **dedicated specification** will define:

* The complete schema of `prometeu.json`
* Dependency version semantics
* Resolution order and override rules
* Tooling expectations (compiler, build system, CI)

This addendum exists to explicitly state the boundary:

> **`prometeu.json` is a compiler concern; dependency management is not part of the VM or bytecode execution model.**