94 lines
3.2 KiB
Markdown
94 lines
3.2 KiB
Markdown
---
|
|
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`
|