87 lines
3.5 KiB
Markdown
87 lines
3.5 KiB
Markdown
---
|
|
id: PLN-0157
|
|
ticket: system-os-cartridge-switch-orchestrator
|
|
title: Introduce SystemOS Game Switch Target Contract
|
|
status: done
|
|
created: 2026-07-05
|
|
ref_decisions: [DEC-0039]
|
|
tags: [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`
|