---
id: PLN-0153
ticket: foreground-stack-game-pause-shell-vm-backed
title: Specify VM Session Ownership and Background-Ready Scheduling
status: done
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