prometeu-studio/docs/pbs/specs/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,
• app entry information,
• 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:

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

Rules:

• magic identifies a Prometeu cartridge manifest,
• cartridge_version identifies the cartridge manifest format line,
• entrypoint identifies the runtime entrypoint,
• capabilities declares the cartridge's requested runtime capabilities,
• asset_table and preload remain separate concerns.

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.

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

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>,
• 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:

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