prometeu-studio/docs/specs/compiler-languages/pbs/7. Cartridge Manifest and Runtime Capabilities Specification.md

# Cartridge Manifest and Runtime Capabilities Specification

Status: Draft v1 (Temporary)  
Applies to: `manifest.json` in Prometeu cartridges, runtime capability declaration, and loader capability input

## 1. Purpose

This document defines the current cartridge manifest contract relevant to runtime loading.

Its purpose is to stabilize:

- the JSON surface consumed by the cartridge loader,
- the declaration of cartridge-requested runtime capabilities,
- the boundary between cartridge packaging and loader authority,
- the conversion from manifest-facing capability names to runtime capability flags.

This document is intentionally temporary and limited.
It does not define cartridge publishing, signing, or store policy.

## 2. Scope

This document defines:

- the role of `manifest.json` in cartridge loading,
- the current required manifest fields,
- the new `capabilities` field,
- the nominal capability enumeration used in JSON,
- the mapping from nominal capabilities to runtime `CapFlags`,
- the role of the loader when combining manifest capabilities with PBX `SYSC`.

This document does not define:

- the full package format beyond the current directory cartridge contract,
- policy UI or permission prompts,
- cartridge signing or trust chains,
- final platform grant policy when the host wants to reduce requested capabilities.

## 3. Current Cartridge Manifest Role

The cartridge manifest is an external load-time descriptor for a cartridge.

It is not compiled from PBS source directly.
It is produced by cartridge packaging tooling and consumed by the runtime loader.

The manifest currently carries:

- cartridge identity and metadata,
- asset metadata,
- preload metadata.

This document adds runtime capability declaration to that same manifest.

## 4. Manifest Shape

The current manifest shape relevant to this document is:

```json
{
  "magic": "PMTU",
  "cartridge_version": 1,
  "app_id": 1001,
  "title": "Example",
  "app_version": "1.0.0",
  "app_mode": "game",
  "capabilities": ["gfx", "input"],
  "asset_table": [],
  "preload": []
}
```

Rules:

- `magic` identifies a Prometeu cartridge manifest,
- `cartridge_version` identifies the cartridge manifest format line,
- `capabilities` declares the cartridge's requested runtime capabilities,
- `asset_table` and `preload` remain separate concerns.
- `manifest.json` MUST NOT declare nominal entrypoint authority for PBS v1 executable boot.
- Runtime boot authority is the physical published entrypoint at function index `0`.

## 5. `capabilities`

### 5.1 General rules

`capabilities` is a manifest-facing nominal list.

Rules:

- `capabilities` is optional,
- when omitted, it behaves as an empty list,
- capability names are canonical lowercase identifiers,
- duplicate entries are invalid,
- unknown capability names are manifest errors.

### 5.2 Nominal capability set

The current nominal capability set is:

- `system`
- `gfx`
- `input`
- `audio`
- `fs`
- `log`
- `asset`
- `bank`

These names are the normative manifest-facing representation.

For the low-level PBS asset host surface, the capability spelling MUST remain `asset` in the singular.
PBS SDK owner names such as `LowAssets` do not change the manifest/runtime capability spelling.

## 6. Relationship to Runtime `CapFlags`

The runtime may continue to represent capabilities internally as a bitflag set.

That internal representation is an implementation detail.

The normative external model is:

- a nominal capability enum in the manifest,
- deterministic conversion by the loader into runtime flags.

Canonical mapping:

- `system` -> `SYSTEM`
- `gfx` -> `GFX`
- `input` -> `INPUT`
- `audio` -> `AUDIO`
- `fs` -> `FS`
- `log` -> `LOG`
- `asset` -> `ASSET`
- `bank` -> `BANK`

For asset host bindings, PBS declarations MUST use `[Capability(name = "asset")]` so that host admission, PBX host binding metadata, and cartridge capability checks all converge on the same runtime flag.

This means the recommended runtime design is:

1. deserialize `capabilities` into a nominal enum or equivalent validated representation,
2. convert that validated set into internal `CapFlags`,
3. use those flags during host-binding resolution.

## 7. Loader Semantics

The loader consumes both:

- the cartridge manifest,
- and the PBX `SYSC` table.

Required behavior:

1. parse `manifest.json`,
2. parse `capabilities`,
3. convert the nominal capability list to internal capability flags,
4. parse `program.pbx`,
5. resolve each `SYSC` entry against the host registry,
6. obtain required capabilities from resolved syscall metadata,
7. fail if required capabilities are not granted by the manifest/policy environment.

The manifest alone does not make a program valid.
The manifest must be consistent with the actual syscalls required by the PBX.

## 8. Requested vs Granted Authority

The manifest declares requested cartridge capabilities.

The loader/runtime environment is the authority that decides what is granted.

Current direction:

- in the initial runtime model, the manifest may act as the immediate source of granted capabilities,
- a future platform policy layer may reduce or deny requested capabilities before final load.

Normative rule:

- the compiler does not grant capabilities,
- the PBX does not grant capabilities,
- cartridge/runtime loading is the authority boundary.

## 9. Relationship to Compiler and Packer

Responsibilities are split as follows:

Compiler:

- compiles source to PBX,
- emits `SYSC`,
- emits `HOSTCALL <sysc_index>`,
- computes deterministic `requiredCapabilities` from admitted host bindings for packer tooling,
- does not grant authority.

Packer:

- produces the cartridge manifest,
- declares requested runtime capabilities,
- packages `manifest.json`, `program.pbx`, and assets.

Loader:

- reads the manifest,
- derives or receives granted capability flags,
- validates those capabilities against PBX host requirements.

## 10. Validation Rules

The cartridge manifest must fail validation if:

1. `capabilities` contains an unknown name,
2. `capabilities` contains duplicates,
3. `capabilities` is not an array of strings or nominal enum values under the chosen serialization form.

Cartridge load must fail if:

1. the manifest omits a capability required by a resolved `SYSC` entry,
2. a future platform policy denies a capability required by a resolved `SYSC` entry.

## 11. Serialization Guidance

The recommended manifest-facing model is a nominal enum list, not numeric masks.

Recommended JSON:

```json
{
  "capabilities": ["gfx", "input", "audio"]
}
```

Rejected as normative surface:

- raw integer bitmasks,
- hex masks,
- unnamed positional arrays.

Rationale:

- nominal capability names are readable,
- manifest diffs remain understandable,
- packer and tooling validation is straightforward,
- runtime may still use bitflags internally after conversion.

## 12. Current Decision Summary

The current temporary contract is:

1. `manifest.json` is the cartridge-facing load descriptor.
2. `capabilities` is declared in `manifest.json`, not in `prometeu.json`.
3. `capabilities` uses nominal canonical names such as `gfx` and `audio`.
4. The runtime may keep using internal `CapFlags`.
5. The loader converts nominal manifest capabilities into internal flags.
6. PBX `SYSC` declares required host bindings, not authority.
7. Loader validation fails if PBX host requirements exceed granted cartridge capabilities.
8. `manifest.json` is not entrypoint authority for PBS v1 boot.