Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
Add structural Fn signatures, typed capture environments, indirect calls and Trait dispatch while preserving logical parameter and result groups, ownership and budgets. Remove guest coroutine execution and legacy loading. Activate bounded sealed PBX v1 with mandatory capture metadata, preserve frame continuations and root return results, and migrate producers and shipped cartridges. Publish coordinated specs, handoffs and the completed runtime lesson. Validation: 880 workspace tests passed, 9 existing tests ignored; both cartridges completed six production-host frames.
228 lines
7.8 KiB
Markdown
228 lines
7.8 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`
|
|
|
|
`app_mode` is the runtime profile discriminator. No separate manifest `target`
|
|
field participates in profile selection.
|
|
|
|
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.
|
|
|
|
## 5.1 Runtime Profiles
|
|
|
|
`Game` and `System` are distinct runtime profiles.
|
|
|
|
`Game` cartridges use the game pipeline. The game profile owns the public game
|
|
surfaces for frame composition, GFX, game input, banks, sprites, and
|
|
memory-card-style persistence.
|
|
|
|
`System` cartridges use a Runtime/Hub pipeline dedicated to system UI and app
|
|
hosting. The system profile must not inherit the game stdlib or game ABI as its
|
|
public authoring surface. In particular, `System` must not expose
|
|
`FrameComposer`, `Gfx`, game `Input`, banks, sprites, or game memory cards as
|
|
public profile APIs.
|
|
|
|
Future `System` APIs may be transported through syscalls, but syscall transport
|
|
does not define the conceptual ABI boundary. The author-facing contract for
|
|
system apps is a dedicated `System` profile ABI and stdlib/framework.
|
|
|
|
The following contracts are intentionally deferred from this cartridge chapter:
|
|
|
|
- complete WindowManager design;
|
|
- component tree and lifecycle semantics;
|
|
- rich invalidation and transitions;
|
|
- public PBS `System` ABI;
|
|
- multitasking and scheduler semantics;
|
|
- detailed `System` filesystem semantics.
|
|
|
|
The positive filesystem contract for `System` remains owned by the dedicated
|
|
filesystem discussion/spec work. The only profile rule fixed here is negative:
|
|
`System` does not use game memory cards as its public storage model.
|
|
|
|
## 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.
|
|
|
|
Directory cartridges are also the only form discovered by the v1 local Home
|
|
games library. When a host provides `--games-root <dir>`, discovery scans only
|
|
immediate child directories under that root. Each child directory is a candidate
|
|
cartridge.
|
|
|
|
For the v1 Home games library:
|
|
|
|
- a candidate must have a valid `manifest.json`;
|
|
- the manifest must declare `app_mode: "Game"`;
|
|
- the library retains the loaded manifest data, `title`, `app_id`,
|
|
`app_version`, the internal cartridge path, and discovery metadata;
|
|
- the library entry identity is the input to the SystemOS Game switch target;
|
|
- `app_id` is the v1 identity used to distinguish same-Game resume from
|
|
different-Game destructive replacement;
|
|
- invalid candidates are logged or reported as diagnostics and omitted from the
|
|
Home list;
|
|
- valid non-Game cartridges are omitted from the Game library.
|
|
|
|
Discovery reads metadata for cataloging. It does not replace the normal
|
|
cartridge loader used when firmware starts the selected cartridge.
|
|
|
|
Selecting a discovered Game from Home is not cartridge self-execution and is not
|
|
guest-controlled. The cartridge path is consumed by firmware/SystemOS, which
|
|
owns same-Game resume, different-Game replacement, failure recovery, and VM
|
|
session creation policy.
|
|
|
|
### Packaged `.pmc` form
|
|
|
|
This form is recognized conceptually by the loader boundary, but its actual load path is not implemented yet.
|
|
|
|
Packaged `.pmc` cartridges are not discovered by the v1 Home games library.
|
|
|
|
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.
|
|
|
|
## Program Registry v1 integration
|
|
|
|
Program payloads MUST use the PBX v1 envelope and mandatory sections defined in [Program Registry and PBX v1](02c-program-registry-and-pbx-v1.md#pbx-v1-encoding). The file limit is 64 MiB and Code is limited to 32 MiB. Unsupported versions are rejected; runtime examples are regenerated rather than converted by a compatibility loader. The existing func_id = 0 boot authority is unchanged.
|
|
|
|
## Fn Execution Boundary
|
|
|
|
Typed Fn callbacks execute as ordinary guest calls on the single VM context. Boot remains physical FunctionId 0; preparation requires an empty capture environment and existing argument checks. FRAME_SYNC preserves context for next-PC resumption; successful last-root RET completes entry and leaves rooted results before threshold GC. No native callback registration, retention or reentry API is introduced; raw HeapRef/ValueSnapshot copies do not establish guest roots or authorize cross-session imports. Syscalls remain non-first-class.
|