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

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

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.

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;
• 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.