83 lines
3.8 KiB
Markdown
83 lines
3.8 KiB
Markdown
---
|
|
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
|