158 lines
4.1 KiB
Markdown
158 lines
4.1 KiB
Markdown
# 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"
|
|
}
|
|
```
|
|
|
|
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`](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 the `assets.pa` envelope, asset table semantics, preload lifecycle, and residency semantics.
|