prometeu-runtime/docs/specs/pbs/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:

{
  "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:

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