---
id: PLN-0162
ticket: system-os-cartridge-switch-orchestrator
title: Specify Game Switch Contract And Direct Boot Separation
status: done
created: 2026-07-05
ref_decisions: [DEC-0039]
tags: [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`