prometeu-runtime/discussion/workflow/plans/PLN-0153-specify-vm-session-ownership-and-background-ready-scheduling.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0153	foreground-stack-game-pause-shell-vm-backed	Specify VM Session Ownership and Background-Ready Scheduling	done	2026-07-04	DEC-0038	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