# 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

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

```json
"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.

```json
"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:

```json
"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.

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

Rules:

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

---

### `git`

Git-based dependency.

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

  ```json
  "version": "0.3.1"
  ```

* Range:

  ```json
  "version": ">=0.2.0 <1.0.0"
  ```

* Latest:

  ```json
  "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**.