prometeu-runtime/docs/runtime/specs/13-cartridge.md

Cartridges

Domain: cartridge package Function: normative

This chapter defines the cartridge contract consumed by the current runtime.

1 Scope

A cartridge is the distributable unit loaded by firmware/runtime.

In the current implementation, the supported dev/runtime form is a directory containing:

• manifest.json
• program.pbx
• optional assets.pa

The loader also recognizes .pmc as a future packaged form, but packaged cartridge loading is not implemented yet.

2 Cartridge Metadata

The runtime currently expects the following manifest fields:

{
  "magic": "PMTU",
  "cartridge_version": 1,
  "app_id": 1234,
  "title": "My Game",
  "app_version": "1.0.0",
  "app_mode": "Game",
  "entrypoint": "main"
}

Additional manifest-supported fields include:

• capabilities
• asset_table
• preload

3 Required Fields

Current required manifest fields:

• magic
• cartridge_version
• app_id
• title
• app_version
• app_mode
• entrypoint

Current required file payloads:

• program.pbx

Optional file payloads:

• assets.pa

4 Runtime Validation Rules

The current loader validates:

• magic == "PMTU"
• cartridge_version == 1
• manifest parse validity
• capability normalization
• presence of program.pbx

If validation fails, cartridge loading is rejected before execution.

5 App Mode and Entrypoint

app_mode controls firmware launch behavior:

• Game
• System

entrypoint is passed to the VM initialization flow and may be resolved as a symbol or function identifier according to the VM/runtime contract.

6 Assets and Preload

If present, the manifest may provide:

• asset_table: runtime asset descriptors;
• preload: initial residency requests.

If assets.pa exists, its bytes become the cartridge asset payload used by the asset manager during cartridge initialization.

7 Runtime Forms

Directory form

This is the working runtime/dev form used by the current loader.

Packaged .pmc form

This form is recognized conceptually by the loader boundary, but its actual load path is not implemented yet.

The cartridge spec therefore distinguishes:

• supported current load form;
• reserved future distribution form.

8 Relationship to Other Specs

• 12-firmware-pos-and-prometeuhub.md defines how firmware consumes cartridge metadata.
• 14-boot-profiles.md defines cartridge selection at boot.
• 15-asset-management.md defines asset table and residency semantics.