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"
}

Additional manifest-supported fields include:

• capabilities

3 Required Fields

Current required manifest fields:

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

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
• when Asset capability is declared, presence of valid assets.pa before asset bootstrap

If validation fails, cartridge loading is rejected before execution.

5 App Mode and Boot Protocol

app_mode controls firmware launch behavior:

• Game
• System

Cartridge boot is protocol-driven, not manifest-driven.

The executable entrypoint of a valid cartridge is always func_id = 0.

This means:

• manifest.json does not select the callable to execute;
• firmware/runtime loads the cartridge and starts execution from func_id = 0;
• nominal exports may exist for linking or introspection, but they do not hold boot authority.

6 Assets and Preload

assets.pa is the runtime-facing asset artifact consumed by the current runtime.

assets.pa v1 is an autocontained binary with:

• fixed binary prelude;
• JSON header;
• binary payload region.

The fixed prelude includes, at minimum:

• magic
• schema_version
• header_len
• payload_offset

It may additionally include:

• flags
• reserved
• header_checksum

The JSON header carries:

• asset_table
• preload

asset_table and preload are therefore no longer the primary runtime contract of manifest.json.

preload is structurally validated as part of assets.pa bootstrap:

• each preload entry is { asset_id, slot };
• asset_id uses 32-bit signed integer semantics;
• each preload.asset_id must resolve to an entry in the same asset_table;
• no two preload entries may claim the same (bank_type, slot) pair once bank_type is resolved from asset_table.

Runtime lifecycle:

• asset_table is loaded from assets.pa and remains live while the cartridge is running;
• preload is loaded from assets.pa, consumed during cartridge initialization, and may be discarded after boot;
• payload bytes are resolved from the payload region using offsets relative to payload_offset.

Runtime loading policy:

• cartridges without assets.pa remain valid when Asset capability is not declared;
• cartridges that declare Asset capability must provide valid assets.pa;
• assets.pa with invalid preload references or preload slot clashes is structurally invalid;
• failure must occur as early as cartridge bootstrap, before preload execution.

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 the assets.pa envelope, asset table semantics, preload lifecycle, and residency semantics.