VM Context Ownership for Resident Game and VM-Backed Shell
This commit is contained in:
@@ -0,0 +1,92 @@
|
||||
---
|
||||
id: PLN-0148
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Introduce VM Session Registry and Identity
|
||||
status: open
|
||||
created: 2026-07-04
|
||||
ref_decisions: [DEC-0038]
|
||||
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
DEC-0038 requires every VM-backed process to own its own mutable VM context instead of sharing `Firmware.vm`. This plan introduces the identity and registry layer required before moving runtime state or changing cartridge loading.
|
||||
|
||||
The implementation must make VM session ownership explicit inside `SystemOS`. A VM-backed Game task and a VM-backed Shell task must be able to coexist as distinct sessions, even before all execution paths are migrated to session-owned VMs.
|
||||
|
||||
## Objective
|
||||
|
||||
Add a `VmSession` model and registry owned by `SystemOS`, keyed by a stable session identity tied to the owning task/process. The registry must support creating, retrieving, and validating VM sessions for VM-backed Game and Shell tasks.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Source decision: DEC-0038.
|
||||
- Existing foreground/task/process lifecycle from DEC-0037 remains authoritative.
|
||||
- Must be implemented before PLN-0149, PLN-0150, PLN-0151, and PLN-0152.
|
||||
|
||||
## Scope
|
||||
|
||||
- Add a session identity type, preferably `VmSessionId`, with a deliberate mapping from the owning `TaskId`.
|
||||
- Add a `VmSession` data structure containing at least:
|
||||
- owning `TaskId`;
|
||||
- owning process id or process lookup path;
|
||||
- `app_id`, title, version, and `AppMode`;
|
||||
- initial placeholder for the session-owned `VirtualMachine`;
|
||||
- initial placeholder for session-owned runtime state to be populated by PLN-0149.
|
||||
- Add a registry under `crates/console/prometeu-system/src/services/` or an equivalent existing services module.
|
||||
- Expose creation and lookup through `crates/console/prometeu-system/src/os/facades/sessions.rs`.
|
||||
- Update `SystemOS` construction in `crates/console/prometeu-system/src/os/system_os.rs` to own the registry.
|
||||
- Enforce V1 uniqueness:
|
||||
- at most one resident Game session;
|
||||
- one foreground Shell task at a time;
|
||||
- same `app_id` resident Game relaunch maps to the existing resident session rather than creating a second Game session.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not move all VM runtime fields yet; that is PLN-0149.
|
||||
- Do not route cartridge loading through sessions yet; that is PLN-0150.
|
||||
- Do not remove `Firmware.vm` yet.
|
||||
- Do not implement general background execution.
|
||||
- Do not allow Game-to-Game switching.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Inspect `TaskId`, process ids, and `ProcessKind` definitions in `crates/console/prometeu-system/src/services/task/` and `crates/console/prometeu-system/src/services/process/`.
|
||||
2. Add the VM session module with a small API:
|
||||
- create session for an existing VM-backed task/process;
|
||||
- get immutable/mutable session by task id;
|
||||
- get resident Game session by `app_id`;
|
||||
- reject incompatible duplicate Game sessions.
|
||||
3. Wire the registry into `SystemOS`.
|
||||
4. Extend `SessionsFacade::create_vm_game_task` and `create_vm_shell_task` so task creation also creates a VM session record.
|
||||
5. Keep native Shell task creation out of the VM session registry.
|
||||
6. Add focused unit tests under `prometeu-system` for registry identity and duplicate handling.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- `SystemOS` owns a VM session registry.
|
||||
- Creating a VM Game task creates exactly one VM session associated with that task.
|
||||
- Creating a VM Shell task creates exactly one VM session associated with that task.
|
||||
- Creating a native Shell task creates no VM session.
|
||||
- Attempting to create a second resident Game session for a different `app_id` is rejected or routed through the existing lifecycle rejection path.
|
||||
- Relaunching the same resident Game can resolve the existing VM session by `app_id`.
|
||||
- No firmware state transition depends on the new registry yet except through task/session creation.
|
||||
|
||||
## Tests
|
||||
|
||||
- `cargo test -p prometeu-system`
|
||||
- Add unit tests for:
|
||||
- VM Game task creates a VM session;
|
||||
- VM Shell task creates a VM session;
|
||||
- native Shell task does not create a VM session;
|
||||
- lookup by `TaskId`;
|
||||
- same resident Game `app_id` resolves to the existing session;
|
||||
- different resident Game `app_id` remains blocked under V1.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `crates/console/prometeu-system/src/os/system_os.rs`
|
||||
- `crates/console/prometeu-system/src/os/facades/sessions.rs`
|
||||
- `crates/console/prometeu-system/src/services/mod.rs`
|
||||
- New or extended module under `crates/console/prometeu-system/src/services/`
|
||||
- `crates/console/prometeu-system/src/lib.rs` if exports are required
|
||||
@@ -0,0 +1,99 @@
|
||||
---
|
||||
id: PLN-0149
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Move VM Runtime State Into VM Sessions
|
||||
status: open
|
||||
created: 2026-07-04
|
||||
ref_decisions: [DEC-0038]
|
||||
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
DEC-0038 states that mutable VM context must belong to the VM-backed process session, not to firmware or a single global runtime slot. The current split has `Firmware.vm: VirtualMachine` and `SystemOS.vm_runtime: VirtualMachineRuntime`, which makes a suspended Game vulnerable to VM-backed Shell execution.
|
||||
|
||||
This plan migrates mutable per-application VM runtime state into the session model introduced by PLN-0148 while keeping global OS services global.
|
||||
|
||||
## Objective
|
||||
|
||||
Make each VM session own the state needed to suspend and later resume that VM-backed process without being overwritten by another VM-backed process.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Source decision: DEC-0038.
|
||||
- Requires PLN-0148.
|
||||
- Must precede full cartridge-loading and scheduler migration in PLN-0150 and PLN-0151.
|
||||
|
||||
## Scope
|
||||
|
||||
- Classify `VirtualMachineRuntime` fields into session-owned versus global OS-owned state.
|
||||
- Move session-owned fields into the `VmSession` context.
|
||||
- Keep global services in `SystemOS`, including:
|
||||
- `LogService`;
|
||||
- process/task/window managers;
|
||||
- foreground stack;
|
||||
- durable `MemcardService`;
|
||||
- global render publication authority or worker coordination that must remain host-facing.
|
||||
- Treat these as session-owned unless proven otherwise during implementation:
|
||||
- `VirtualMachine`;
|
||||
- current cartridge identity;
|
||||
- frame and tick counters;
|
||||
- lifecycle delivery bookkeeping;
|
||||
- crash report for that session;
|
||||
- pause/debug flags that apply to that session;
|
||||
- per-session open files, handles, and staging state used by VM syscalls.
|
||||
- Keep durable memcard contents keyed by `app_id`; do not turn save data into session-private durable storage.
|
||||
- Update `VmFacade` and VM runtime helpers so callers can operate on a selected session.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not redesign render workers beyond separating session-local render command state from global presentation authority.
|
||||
- Do not implement background execution.
|
||||
- Do not change syscall semantics except where required to route state through the active session.
|
||||
- Do not remove host debugger features; preserve or adapt their access path.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Add an internal field-by-field classification comment or test-only assertion near `VirtualMachineRuntime` before moving fields.
|
||||
2. Introduce a session runtime/context type in the VM session module or by splitting `VirtualMachineRuntime` into:
|
||||
- session-local runtime;
|
||||
- global render/log/runtime services.
|
||||
3. Move `VirtualMachine` ownership from firmware placeholder/session stub into the session context.
|
||||
4. Move per-cartridge and per-frame state from `SystemOS.vm_runtime` into the session context.
|
||||
5. Move `open_files`, `next_handle`, and VM syscall staging state out of global `SystemOS` if they are VM-session specific.
|
||||
6. Update `VmRuntimeHost` in `crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs` to receive session-local state plus references to required global services.
|
||||
7. Update `VmFacade` in `crates/console/prometeu-system/src/os/facades/vm.rs` with explicit session-targeted methods.
|
||||
8. Preserve temporary compatibility methods only where needed for existing host/debugger code, and mark them as active-session views rather than canonical global ownership.
|
||||
9. Add tests proving two VM sessions can hold different app identity and counters at the same time.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- No canonical VM state lives in `Firmware`.
|
||||
- `SystemOS` can hold at least two VM sessions with independent `VirtualMachine` and per-session runtime state.
|
||||
- VM session A and VM session B can have different `app_id`, title, frame counters, lifecycle delivery history, crash report, open file handles, and debug pause state.
|
||||
- Durable memcard contents remain shared by `app_id` according to the existing memcard contract.
|
||||
- Global render ownership remains controlled by SystemOS/host-facing runtime services, not by individual sessions.
|
||||
- Existing `prometeu-system` VM runtime tests still pass after adapting their setup.
|
||||
|
||||
## Tests
|
||||
|
||||
- `cargo test -p prometeu-system`
|
||||
- `cargo test -p prometeu-firmware`
|
||||
- Add tests for:
|
||||
- independent session app identity;
|
||||
- independent tick/logical-frame counters;
|
||||
- independent lifecycle delivery bookkeeping;
|
||||
- VM Shell session initialization does not mutate resident Game session identity;
|
||||
- session-scoped file handles do not collide across sessions.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `crates/console/prometeu-system/src/services/vm_runtime/`
|
||||
- VM session module introduced by PLN-0148
|
||||
- `crates/console/prometeu-system/src/os/facades/vm.rs`
|
||||
- `crates/console/prometeu-system/src/os/system_os.rs`
|
||||
- `crates/console/prometeu-system/src/os/facades/fs.rs`
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
|
||||
- `crates/host/prometeu-host-desktop-winit/src/debugger.rs`
|
||||
- `crates/host/prometeu-host-desktop-winit/src/runner.rs`
|
||||
- `crates/host/prometeu-host-desktop-winit/src/stats.rs`
|
||||
@@ -0,0 +1,90 @@
|
||||
---
|
||||
id: PLN-0150
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Route Cartridge Loading Through VM Sessions
|
||||
status: open
|
||||
created: 2026-07-04
|
||||
ref_decisions: [DEC-0038]
|
||||
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
DEC-0038 requires cartridge loading to create or activate a VM-backed process session instead of initializing a single global VM. The current `LoadCartridgeStep` initializes `ctx.os.vm().initialize(ctx.vm, &cartridge)` before task/session ownership is selected.
|
||||
|
||||
This plan moves cartridge initialization behind session services so Game and VM-backed Shell loading cannot overwrite each other.
|
||||
|
||||
## Objective
|
||||
|
||||
Route Game and VM Shell cartridge loading through the VM session registry and initialize the cartridge inside the target session-owned VM context.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Source decision: DEC-0038.
|
||||
- Requires PLN-0148.
|
||||
- Requires enough of PLN-0149 to expose session-owned VM/runtime initialization.
|
||||
- Must precede the end-to-end coexistence validation in PLN-0152.
|
||||
|
||||
## Scope
|
||||
|
||||
- Replace direct global VM initialization in `LoadCartridgeStep`.
|
||||
- Add a session/facade operation that:
|
||||
- selects an existing resident Game session when the same `app_id` is relaunched;
|
||||
- rejects or reports different resident Game launches under V1;
|
||||
- creates a new VM Shell session for a Shell cartridge;
|
||||
- initializes the cartridge inside the selected session VM.
|
||||
- Keep asset manager initialization aligned with the foreground cartridge being launched.
|
||||
- Ensure `AppCrashesStep` receives initialization failures from the target session.
|
||||
- Update Hub cartridge selection logic so resume versus load is based on lifecycle/session identity, not global VM identity.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not implement multiple resident Games.
|
||||
- Do not implement background execution.
|
||||
- Do not redesign cartridge format or asset packaging.
|
||||
- Do not broaden Shell windowing behavior beyond the existing one-foreground-Shell model.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Add a `load_vm_cartridge` or equivalent method to `SessionsFacade` or `VmFacade`.
|
||||
2. Make the method return an execution target:
|
||||
- existing Game task for same resident `app_id`;
|
||||
- new Game task for first Game launch;
|
||||
- new VM Shell task for Shell launch;
|
||||
- structured error/crash report for invalid VM initialization;
|
||||
- explicit lifecycle error for blocked second Game.
|
||||
3. Update `crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs` to call the facade method instead of initializing `ctx.vm`.
|
||||
4. Update `crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs` so same-Game relaunch checks session/lifecycle state rather than `ctx.os.vm().current_app_id()`.
|
||||
5. Preserve AppMode-based transition:
|
||||
- Game target transitions to `GameRunning`;
|
||||
- Shell target creates/focuses a window and transitions to `ShellRunning`.
|
||||
6. Adapt crash tests and resident-game relaunch tests in firmware.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- `LoadCartridgeStep` no longer initializes a global firmware VM.
|
||||
- Loading a Shell cartridge creates/initializes a Shell VM session.
|
||||
- Loading the first Game cartridge creates/initializes the resident Game VM session.
|
||||
- Clicking the same resident Game from Hub resumes the existing Game session without reinitializing it.
|
||||
- Attempting to load a different Game while one resident Game exists remains blocked under V1 with a controlled outcome.
|
||||
- VM initialization failure still transitions to `AppCrashesStep`.
|
||||
|
||||
## Tests
|
||||
|
||||
- `cargo test -p prometeu-firmware`
|
||||
- `cargo test -p prometeu-system`
|
||||
- Add or update firmware tests for:
|
||||
- first Game load creates one session and enters `GameRunning`;
|
||||
- same Game relaunch resumes existing task/session;
|
||||
- VM Shell load creates a distinct session;
|
||||
- Shell load does not change resident Game session app identity;
|
||||
- invalid cartridge reports `CrashReport::VmInit`.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs`
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs`
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
|
||||
- `crates/console/prometeu-system/src/os/facades/sessions.rs`
|
||||
- `crates/console/prometeu-system/src/os/facades/vm.rs`
|
||||
- VM session module introduced by PLN-0148
|
||||
@@ -0,0 +1,92 @@
|
||||
---
|
||||
id: PLN-0151
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Schedule Foreground VM Session Ticks
|
||||
status: open
|
||||
created: 2026-07-04
|
||||
ref_decisions: [DEC-0038]
|
||||
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
DEC-0038 separates session ownership from foreground ownership and states that V1 does not provide general background execution. The runtime therefore needs an explicit scheduler path that ticks the VM session eligible for foreground execution, while leaving suspended resident Game sessions intact.
|
||||
|
||||
## Objective
|
||||
|
||||
Make firmware and SystemOS tick the VM session associated with the current foreground VM-backed task, instead of ticking a global VM/runtime pair.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Source decision: DEC-0038.
|
||||
- Requires PLN-0148.
|
||||
- Requires PLN-0149.
|
||||
- Requires PLN-0150 for loaded cartridges to map to sessions.
|
||||
|
||||
## Scope
|
||||
|
||||
- Add scheduler/facade operations that tick a specific VM session by `TaskId`.
|
||||
- Update `GameRunningStep` to tick the Game session identified by its `task_id`.
|
||||
- Update `ShellRunningStep` to tick only VM-backed Shell sessions.
|
||||
- Ensure native Shell foreground state performs native profile updates without ticking any VM session.
|
||||
- Keep suspended Game sessions non-executing while Hub or Shell is foreground.
|
||||
- Preserve lifecycle event delivery:
|
||||
- pause/resume events go to the resident Game session;
|
||||
- Shell lifecycle events, if any, remain scoped to the Shell session.
|
||||
- Preserve host debugger pause/step behavior against the active VM session view.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not add background execution classes yet.
|
||||
- Do not allow multiple simultaneous VM ticks in one host frame.
|
||||
- Do not implement general service/player processes.
|
||||
- Do not change the 60 Hz firmware tick contract.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Add `SystemOS` facade methods for:
|
||||
- ticking a VM session by task id;
|
||||
- querying whether a task is VM-backed;
|
||||
- exposing the active VM session to host/debugger tooling.
|
||||
2. Update `crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs` to tick through the task/session facade.
|
||||
3. Update `crates/console/prometeu-firmware/src/firmware/firmware_step_shell_running.rs` to branch on process kind:
|
||||
- VM Shell ticks its VM session;
|
||||
- native Shell runs native profile logic only.
|
||||
4. Remove direct `ctx.vm` use from Game/Shell execution steps.
|
||||
5. Ensure resident Game pause budget can deliver one final pause tick and then stop ticking once suspended.
|
||||
6. Update host/debugger active VM access paths to resolve through the foreground session.
|
||||
7. Add regression tests for tick counters across Game, Hub, native Shell, and VM Shell transitions.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- A suspended Game session does not advance while Hub is foreground.
|
||||
- A suspended Game session does not advance while a Shell is foreground.
|
||||
- A VM Shell session advances while that VM Shell is foreground.
|
||||
- A native Shell does not tick any VM session.
|
||||
- Returning from Hub to resident Game resumes ticking the same Game session.
|
||||
- Host debugger and stats read the active VM session, not a stale global VM.
|
||||
|
||||
## Tests
|
||||
|
||||
- `cargo test -p prometeu-firmware`
|
||||
- `cargo test -p prometeu-system`
|
||||
- `cargo test -p prometeu-host-desktop-winit`
|
||||
- Add tests for:
|
||||
- Game tick count freezes after Home suspension;
|
||||
- VM Shell tick count advances independently;
|
||||
- native Shell does not advance Game tick count;
|
||||
- resume returns to same Game session tick counter;
|
||||
- active-session debugger snapshot uses foreground VM session.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs`
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware_step_shell_running.rs`
|
||||
- `crates/console/prometeu-firmware/src/firmware/prometeu_context.rs`
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
|
||||
- `crates/console/prometeu-system/src/os/facades/vm.rs`
|
||||
- `crates/console/prometeu-system/src/os/facades/lifecycle.rs`
|
||||
- VM session module introduced by PLN-0148
|
||||
- `crates/host/prometeu-host-desktop-winit/src/debugger.rs`
|
||||
- `crates/host/prometeu-host-desktop-winit/src/runner.rs`
|
||||
- `crates/host/prometeu-host-desktop-winit/src/stats.rs`
|
||||
@@ -0,0 +1,86 @@
|
||||
---
|
||||
id: PLN-0152
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Validate Game and VM Shell Session Coexistence
|
||||
status: open
|
||||
created: 2026-07-04
|
||||
ref_decisions: [DEC-0038]
|
||||
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
DEC-0038 was motivated by the concrete failure mode where a resident Game is suspended, a Shell is opened, and Game logs or state unexpectedly continue under the wrong foreground owner. After VM sessions and scheduling are implemented, the system needs explicit regression coverage for this workflow.
|
||||
|
||||
## Objective
|
||||
|
||||
Add end-to-end and integration validation proving a resident Game VM session and a VM-backed Shell session can coexist without overwriting or ticking each other incorrectly.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Source decision: DEC-0038.
|
||||
- Requires PLN-0148, PLN-0149, PLN-0150, and PLN-0151.
|
||||
- Should be executed before closing the broader DEC-0038 implementation thread.
|
||||
|
||||
## Scope
|
||||
|
||||
- Add firmware-level regression tests for:
|
||||
- Game launch;
|
||||
- Home/SystemOS request;
|
||||
- Game pause/suspend;
|
||||
- VM Shell launch;
|
||||
- Shell foreground ticking;
|
||||
- Shell exit;
|
||||
- Hub return;
|
||||
- resident Game resume.
|
||||
- Add system-level tests for independent session state.
|
||||
- Add host-level tests only where active VM/debugger/stat routing cannot be covered at firmware/system level.
|
||||
- Verify logs from the stress cartridge or equivalent test cartridge do not appear while Game is suspended and Shell is foreground.
|
||||
- Verify Shell logs, frames, or tick counters belong to the Shell session.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not introduce new architecture in this plan.
|
||||
- Do not broaden background execution.
|
||||
- Do not rewrite Hub UI behavior except where required to exercise the flow.
|
||||
- Do not depend on manual desktop testing as the only evidence.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Identify or add deterministic test cartridges/helpers that can emit per-session tick/log evidence.
|
||||
2. Add a firmware integration test for `Game -> Home -> VM Shell -> Hub -> same Game`.
|
||||
3. Capture Game session counters before Shell launch and after Shell foreground ticks.
|
||||
4. Assert the Game session counters and lifecycle delivery state remain stable while Shell is foreground.
|
||||
5. Assert the Shell session counters advance while Shell is foreground.
|
||||
6. Assert returning to the same Game resumes the same task/session and then advances the Game counter.
|
||||
7. Add a regression specifically covering the prior symptom: Game `stress` logs must not appear during Shell foreground execution.
|
||||
8. Run the relevant crate tests and record evidence in the plan completion notes when implemented.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- The failing manual scenario is covered by automated tests.
|
||||
- The Game session is suspended and non-ticking while VM Shell is foreground.
|
||||
- The VM Shell session ticks independently.
|
||||
- Returning to Hub and selecting the same Game resumes the resident Game session instead of creating a duplicate process/session.
|
||||
- No test relies on a single global `current_app_id` to infer correctness.
|
||||
|
||||
## Tests
|
||||
|
||||
- `cargo test -p prometeu-system`
|
||||
- `cargo test -p prometeu-firmware`
|
||||
- `cargo test -p prometeu-host-desktop-winit` if host active-session plumbing changed.
|
||||
- Optional manual smoke:
|
||||
- run `cargo run --bin prometeu-host-desktop-winit --profile release --manifest-path crates/host/prometeu-host-desktop-winit/Cargo.toml -- --games-root test-cartridges`;
|
||||
- open Stress Console;
|
||||
- press ESC/Home;
|
||||
- open VM-backed Shell;
|
||||
- verify no Stress logs appear while Shell is foreground;
|
||||
- return and resume Stress Console.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware.rs` tests
|
||||
- `crates/console/prometeu-system/src/os/system_os.rs` tests
|
||||
- `crates/console/prometeu-system/src/services/vm_runtime/tests.rs`
|
||||
- `crates/host/prometeu-host-desktop-winit/src/runner.rs` tests if needed
|
||||
- `test-cartridges/` only if a deterministic VM Shell fixture is missing
|
||||
+82
@@ -0,0 +1,82 @@
|
||||
---
|
||||
id: PLN-0153
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Specify VM Session Ownership and Background-Ready Scheduling
|
||||
status: open
|
||||
created: 2026-07-04
|
||||
ref_decisions: [DEC-0038]
|
||||
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
DEC-0038 locks the runtime direction: VM context is session-owned, firmware orchestrates macro-state, and background execution is out of V1 but must remain a near-term compatible extension. The canonical specs must describe that contract in English so future implementation and debugging do not drift back to a single global VM model.
|
||||
|
||||
## Objective
|
||||
|
||||
Update canonical runtime specifications to document VM session ownership, foreground execution eligibility, render publication authority, and the background-ready shape of the scheduler without committing to background execution in this implementation batch.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Source decision: DEC-0038.
|
||||
- Should be informed by PLN-0148 through PLN-0151 once implementation names settle.
|
||||
- May be done before PLN-0152 if the implementation contract is already stable, but final wording must match implemented APIs.
|
||||
|
||||
## Scope
|
||||
|
||||
- Update the canonical specs under `docs/specs/runtime/` in English.
|
||||
- Document:
|
||||
- each VM-backed process owns one VM session;
|
||||
- VM sessions own mutable VM context;
|
||||
- foreground ownership and execution eligibility are separate concepts;
|
||||
- V1 executes only the foreground VM-backed task, except the existing pause handoff budget;
|
||||
- suspended resident Game sessions preserve VM context but do not tick;
|
||||
- VM-backed Shell sessions have their own VM context;
|
||||
- native Shell does not own a VM session;
|
||||
- durable app data remains keyed by `app_id`;
|
||||
- session-scoped handles and staging state are not durable app data;
|
||||
- global render publication remains SystemOS/host authority.
|
||||
- Add background-ready wording:
|
||||
- scheduler model can later mark sessions or service processes as eligible without changing ownership;
|
||||
- no current guarantee of background progress is introduced.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not write implementation plans into specs.
|
||||
- Do not document background execution as available.
|
||||
- Do not move normative text into `discussion/lessons/`.
|
||||
- Do not create new legacy docs paths.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Locate the most relevant runtime specs, likely:
|
||||
- `docs/specs/runtime/09-events-and-concurrency.md`;
|
||||
- `docs/specs/runtime/12-firmware-pos-and-prometeuhub.md`;
|
||||
- `docs/specs/runtime/14-boot-profiles.md`;
|
||||
- `docs/specs/runtime/16-host-abi-and-syscalls.md` if host/debugger active VM views are affected.
|
||||
2. Add concise normative sections using `MUST`, `MUST NOT`, and `SHALL` where appropriate.
|
||||
3. Keep discussion history out of the spec; cite behavior, not agenda chronology.
|
||||
4. Align terminology with implemented type names from PLN-0148 through PLN-0151.
|
||||
5. Run discussion validation after edits and any repository tests required by touched docs tooling.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Specs explicitly state that VM context is session-owned for VM-backed processes.
|
||||
- Specs explicitly state that native Shell does not own a VM session.
|
||||
- Specs distinguish foreground ownership from future execution eligibility.
|
||||
- Specs state that V1 does not support general background execution.
|
||||
- Specs preserve a future path for background-capable sessions/services without changing VM ownership.
|
||||
- No new framework artifacts are written outside `discussion/`.
|
||||
|
||||
## Tests
|
||||
|
||||
- `discussion validate`
|
||||
- Manual review of touched specs for English-only normative text.
|
||||
- Run repository doc checks if such a command exists; otherwise no code test is required for this plan.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `docs/specs/runtime/09-events-and-concurrency.md`
|
||||
- `docs/specs/runtime/12-firmware-pos-and-prometeuhub.md`
|
||||
- `docs/specs/runtime/14-boot-profiles.md`
|
||||
- `docs/specs/runtime/16-host-abi-and-syscalls.md` if active VM host/debugger wording is needed
|
||||
Reference in New Issue
Block a user