prometeu-studio/docs/specs/random/pbs_old/PBS - prometeu.json specs.md

Prometeu.json — Project Manifest Specification

Status

Draft · Complementary specification to the PBS Linking & Module Model

Purpose

prometeu.json is the project manifest for Prometeu-based software.

Its role is to:

• Identify a Prometeu project
• Declare its dependencies
• Provide input metadata to the compiler and linker

It is not consumed by the Virtual Machine.

---

Design Principles

1. Compiler-owned

   • Only the Prometeu Compiler reads prometeu.json.
   • The VM and runtime never see this file.

2. Declarative, not procedural

   • The manifest declares what the project depends on, not how to resolve it.

3. Closed-world output

   • Compilation + linking produce a single, fully resolved bytecode blob.

4. Stable identity

   • Project identity is explicit and versioned.

---

File Location

prometeu.json must be located at the root of the project.

---

Top-level Structure

{
  "name": "my_project",
  "version": "0.1.0",
  "kind": "app",
  "dependencies": {
    "std": {
      "git": "https://github.com/prometeu/std",
      "version": ">=0.2.0"
    }
  }
}

---

Fields

name

Required

• Logical name of the project
• Used as the default module namespace

Rules:

• ASCII lowercase recommended
• Must be unique within the dependency graph

Example:

"name": "sector_crawl"

---

version

Required

• Semantic version of the project
• Used by the compiler for compatibility checks

Format:

MAJOR.MINOR.PATCH

---

kind

Optional (default: app)

Defines how the project is treated by tooling.

Allowed values:

• app — executable program
• lib — reusable module/library
• system — firmware / system component

---

dependencies

Optional

A map of dependency aliases to dependency specifications.

"dependencies": {
  "alias": { /* spec */ }
}

Alias semantics

• The key is the name by which the dependency is referenced inside this project.
• It acts as a rename / namespace alias.

Example:

"dependencies": {
  "gfx": {
    "path": "../prometeu-gfx"
  }
}

Internally, the dependency will be referenced as gfx, regardless of its original project name.

---

Dependency Specification

Each dependency entry supports the following fields.

path

Local filesystem dependency.

{
  "path": "../std"
}

Rules:

• Relative paths are resolved from the current prometeu.json
• Absolute paths are allowed but discouraged

---

git

Git-based dependency.

{
  "git": "https://github.com/prometeu/std",
  "version": "^0.3.0"
}

The compiler is responsible for:

• Cloning / fetching
• Version selection
• Caching

---

version

Optional version constraint.

Examples:

• Exact:

  "version": "0.3.1"
  

• Range:

  "version": ">=0.2.0 <1.0.0"
  

• Latest:

  "version": "latest"
  

Semantics are defined by the compiler.

---

Resolution Model (Compiler-side)

The compiler must:

1. Load root prometeu.json

2. Resolve all dependencies recursively

3. Apply aliasing rules

4. Detect:

   • Cycles
   • Version conflicts
   • Name collisions

5. Produce a flat module graph

6. Invoke the linker to generate a single Program Image

---

Interaction with the Linker

• prometeu.json feeds the module graph

• The linker:

  • Assigns final function indices
  • Fixes imports/exports
  • Emits a closed bytecode image

After linking:

No module boundaries or dependency information remain at runtime.

---

Explicit Non-Goals

This specification does not define:

• Lockfiles
• Registry formats
• Caching strategies
• Build profiles
• Conditional dependencies

These may be added in future specs.

---

Summary

• prometeu.json is the single source of truth for project identity and dependencies
• Dependency management is compiler-owned
• The VM executes only fully linked bytecode

This file completes the boundary between project structure and runtime execution.