# 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:

```json
{
  "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`](12-firmware-pos-and-prometeuhub.md) defines how firmware consumes cartridge metadata.
- [`14-boot-profiles.md`](14-boot-profiles.md) defines cartridge selection at boot.
- [`15-asset-management.md`](15-asset-management.md) defines asset table and residency semantics.