prometeu-runtime/discussion/workflow/plans/PLN-0131-preserve-direct-cartridge-boot-coverage.md

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

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/