Intrepid/prometeu-runtime
Intrepid/prometeu-runtime
4
0
Fork 0
Code Pull Requests Activity
prometeu-runtime/discussion/workflow/plans/PLN-0157-introduce-systemos-game-switch-target-contract.md

3.5 KiB
Raw Blame History

id ticket title status created ref_decisions tags
PLN-0157 system-os-cartridge-switch-orchestrator Introduce SystemOS Game Switch Target Contract open 2026-07-05
DEC-0039
runtime
os
lifecycle
game
cartridge
architecture

Briefing

DEC-0039 requires Game-to-Game switching under Home/Hub to be owned by SystemOS. Before destructive replacement can be implemented, Hub/Firmware/SystemOS need a small explicit contract for "launch this resolved Game target as a replacement" that is separate from direct boot and from loader internals.

Objective

Introduce a SystemOS-owned Game switch request/target abstraction that can carry a resolved cartridge path or game-library entry from Hub/Home into the switch orchestrator without making the loader or userland the lifecycle authority.

Dependencies

  • Source decision: DEC-0039.
  • Builds on DEC-0037 and DEC-0038 as already implemented.
  • Must be implemented before PLN-0158, PLN-0159, and PLN-0161.

Scope

  • Define a minimal Game switch target type, such as GameSwitchTarget or CartridgeLaunchTarget, in the SystemOS/Firmware boundary.
  • Route Hub game-library launch actions through that target contract instead of treating a path as an implicit lifecycle operation.
  • Keep direct boot/debug boot paths separate from SystemOS Game switching.
  • Add tests proving the target preserves cartridge identity/path without starting lifecycle replacement by itself.

Non-Goals

  • Do not implement destructive replacement in this plan.
  • Do not add .pmc, final catalog UX, or a new launcher UI.
  • Do not change direct CLI/debug boot behavior.
  • Do not add background execution.

Execution Method

  1. Inspect crates/console/prometeu-system/src/services/game_library.rs, crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs, and crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs.
  2. Add a minimal launch target model at the SystemOS/Firmware boundary:
    • resolved cartridge path;
    • optional app_id/title metadata if already available;
    • no loader-owned lifecycle policy.
  3. Update Hub action plumbing so SystemProfileAction::LaunchGame carries the resolved target type or maps immediately into it at the firmware boundary.
  4. Add a placeholder SystemOS/Firmware entry point for Game switching that accepts the target but still delegates to the existing load path until PLN-0158 changes replacement behavior.
  5. Add unit tests for target construction and path propagation.
  6. Keep direct BootTarget::Cartridge behavior unchanged.

Acceptance Criteria

  • There is an explicit type or function contract representing a resolved SystemOS Game switch target.
  • Hub/Home no longer treats a raw path as lifecycle authority.
  • The loader remains a materialization step, not the switch orchestrator.
  • Direct boot/debug boot code paths remain separate and behaviorally unchanged.
  • Tests prove target identity is carried without implicitly closing or loading a Game.

Tests

  • cargo test -p prometeu-system
  • cargo test -p prometeu-firmware
  • cargo test -p prometeu-host-desktop-winit
  • cargo clippy -p prometeu-system -p prometeu-firmware -p prometeu-host-desktop-winit --all-targets -- -D warnings

Affected Artifacts

  • crates/console/prometeu-system/src/services/game_library.rs
  • crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs
  • crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs
  • crates/console/prometeu-firmware/src/firmware/firmware.rs