prometeu-runtime/discussion/workflow/plans/PLN-0162-specify-game-switch-contract-and-direct-boot-separation.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0162	system-os-cartridge-switch-orchestrator	Specify Game Switch Contract And Direct Boot Separation	done	2026-07-05	DEC-0039	runtime os lifecycle game cartridge architecture

Briefing

DEC-0039 must be reflected in the canonical runtime specs after the operational contract is implemented or alongside implementation. The spec must distinguish same-Game resume, Game replacement under SystemOS, and direct boot/debug boot.

Objective

Update the canonical runtime documentation to describe SystemOS Game cartridge switching and to keep direct boot/debug boot separate from Home/Hub-driven Game replacement.

Dependencies

• Source decision: DEC-0039.
• Can be implemented before code if the spec is written as intended behavior.
• Should be reconciled after PLN-0157 through PLN-0161 if implementation names differ from initial plan names.

Scope

• Update relevant files under docs/specs/runtime/, especially:
  • 12-firmware-pos-and-prometeuhub.md;
  • 13-cartridge.md;
  • 14-boot-profiles.md;
  • 09-events-and-concurrency.md if lifecycle events need mention;
  • 10-debug-inspection-and-profiling.md if debugger separation needs note.
• Document:
  • SystemOS authority for Game switching;
  • destructive replacement semantics;
  • optional non-blocking terminate/save event;
  • fresh VM session for new Game;
  • failed switch recovery to Home/Hub;
  • direct boot/debug boot separation;
  • test cartridge evidence requirement.

Non-Goals

• Do not document .pmc or final catalog UX as required.
• Do not specify background execution.
• Do not revise DEC-0037 or DEC-0038 semantics.
• Do not write lesson material; housekeeping will decide lessons after execution.

Execution Method

1. Read the runtime spec files listed in scope.
2. Add a Game switching section in the most appropriate canonical spec file.
3. Cross-reference existing Home/Hub, cartridge, boot profile, and debug boot sections.
4. Ensure language is English and normative enough for future implementers: MUST, MUST NOT, MAY, SHOULD.
5. Verify no non-English agenda language leaks into specs.
6. Run docs grep checks for the newly introduced terms.

Acceptance Criteria

• Specs explicitly distinguish:
  • same-Game pause/resume;
  • Game A to Game B destructive replacement;
  • direct boot/debug boot.
• Specs state that SystemOS owns Game switching policy.
• Specs state that a new Game gets a fresh VM session.
• Specs state that failed switch returns Home/Hub and does not restore the old Game in v1.
• Specs mention Dummy Boy or equivalent two-cartridge evidence only as test evidence, not as runtime feature.
• Documentation is English.

Tests

• rg -n "Game switch|destructive replacement|direct boot|Dummy Boy|VM session" docs/specs/runtime
• discussion validate
• Run code tests only if this plan is implemented together with code changes: cargo test -p prometeu-system -p prometeu-firmware

Affected Artifacts

• docs/specs/runtime/12-firmware-pos-and-prometeuhub.md
• docs/specs/runtime/13-cartridge.md
• docs/specs/runtime/14-boot-profiles.md
• docs/specs/runtime/09-events-and-concurrency.md
• docs/specs/runtime/10-debug-inspection-and-profiling.md