---
id: PLN-0131
ticket: system-run-cart
title: Preserve Direct Cartridge Boot Coverage
status: done
created: 2026-07-03
ref_decisions: [DEC-0035]
tags: []
---

## Briefing

`DEC-0035` removes userland `system.run_cart`, but direct cartridge boot remains
mandatory for development, debugging, automated tests, and future single-game
launch scenarios. This plan protects that path while the guest syscall is
removed.

## Objective

Preserve and test host/CLI/debug direct cartridge boot without relying on a
guest syscall.

## Dependencies

- Source decision: `DEC-0035`.
- Can be implemented after or alongside `PLN-0129` and `PLN-0130`.
- Must not depend on `.pmc`, app catalog, launcher UX, `AGD-0041`, or
  `AGD-0044`.

## Scope

- Identify direct boot entrypoints in `crates/tools/prometeu-cli/src/main.rs`,
  `crates/host/prometeu-host-desktop-winit/src/lib.rs`,
  `crates/host/prometeu-host-desktop-winit/src/debugger.rs`, and firmware
  cartridge loading code.
- Add or preserve tests showing a cartridge can be loaded directly into
  firmware/runtime from host or CLI paths.
- Ensure these paths do not call or require `system.run_cart`.
- Document the distinction between direct boot and guest navigation where
  runtime specs describe boot behavior.

## Non-Goals

- Do not implement `Home -> another Game`.
- Do not add app-callable navigation.
- Do not require `.pmc`.
- Do not redesign cartridge loader internals beyond what is required to keep
  direct boot working.

## Execution Method

1. Trace the CLI/debug direct boot path from cartridge path argument through
   loader, firmware `load_cartridge`, and runtime initialization.
2. Add regression tests at the lowest practical layer proving direct boot still
   reaches `GameRunning` for a valid game cartridge.
3. Add a guard or assertion that direct boot does not depend on `system.run_cart`
   metadata.
4. Update docs/specs to describe direct boot as host/system-controlled.
5. Run targeted CLI/firmware/host tests.

## Acceptance Criteria

- A valid game cartridge can still boot directly from host/CLI/debug paths.
- Direct boot does not depend on `system.run_cart` being in the guest syscall
  registry.
- Existing debugger/handshake metadata that reports cartridge info still works.
- The direct boot behavior is documented as host/system entry, not guest ABI.

## Tests

- Add or preserve firmware tests around `load_cartridge` and `GameRunning`.
- Add or preserve host/CLI tests for cartridge path boot when practical.
- Run `cargo test` for `prometeu-firmware`, `prometeu-host-desktop-winit`, and
  `prometeu-cli` where available.

## Affected Artifacts

- `crates/tools/prometeu-cli/src/main.rs`
- `crates/host/prometeu-host-desktop-winit/src/lib.rs`
- `crates/host/prometeu-host-desktop-winit/src/debugger.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs`
- `docs/specs/runtime/`