# Native Runtime Architecture

Pane's long-term runtime goal is a contained Windows app that owns both the Linux OS runtime and the desktop presentation. The current MVP is not there yet. It uses WSL2, XRDP, and `mstsc.exe` for the launchable Arch desktop while Pane builds the app-owned runtime contract in parallel.

This document is the contract for moving from that bridge to a Pane-owned runtime without drifting into another thin wrapper.

## Current Boundary

Pane currently owns:

- the packaged `pane.exe` app entrypoint,
- the Control Center,
- managed Arch onboarding and repair flows,
- PaneShared user file exchange,
- dedicated runtime storage under `%LOCALAPPDATA%\Pane\runtime\<session>`,
- base OS image registration and SHA-256 verification metadata,
- a user-disk descriptor for future Linux system, package, account, and customization data,
- native host preflight through `pane native-preflight`.
- a guarded WHP partition/vCPU smoke step through `pane native-boot-spike --execute`.

Pane does not yet own:

- booting the Linux kernel or init system from Pane runtime artifacts,
- presenting a Linux framebuffer inside a Pane-owned window,
- app-owned input, clipboard, audio, resize, GPU, or display transport,
- snapshot, export, import, and repair semantics for a booted Pane-owned disk.

## Runtime Decision

The native runtime path should target the Windows Hypervisor Platform (WHP) directly before considering any bundled third-party hypervisor dependency. WHP is the closest fit for Pane's product claim because it lets Pane become the host application that creates the partition, maps memory, creates virtual processors, runs the guest, and owns the surrounding UX.

Pane should not treat QEMU, VirtualBox, Hyper-V Manager, WSL, XRDP, or `mstsc.exe` as the final runtime/display architecture. Those can be temporary references, migration aids, or compatibility comparisons, but the product should not ship as "Pane-owned" if another app is still the real runtime or renderer.

Relevant Microsoft API surfaces:

- https://learn.microsoft.com/en-us/virtualization/api/
- https://learn.microsoft.com/en-us/virtualization/api/hypervisor-platform/hypervisor-platform
- https://learn.microsoft.com/en-us/virtualization/api/hypervisor-platform/funcs/whvrunvirtualprocessor
- https://learn.microsoft.com/en-us/virtualization/hyper-v-on-windows/user-guide/make-integration-service

## Preflight Gate

`pane native-preflight` is the first native-runtime implementation slice. It is intentionally not a boot engine. It answers whether the current host is suitable for the first WHP boot spike and whether Pane runtime artifacts are ready enough to use.

The command checks:

- Windows host requirement,
- supported CPU architecture,
- `WinHvPlatform.dll` loadability,
- required WHP exports such as `WHvGetCapability`, `WHvCreatePartition`, `WHvSetupPartition`, `WHvCreateVirtualProcessor`, `WHvRunVirtualProcessor`, and `WHvMapGpaRange`,
- hypervisor presence reported by WHP,
- runtime storage preparation,
- verified base OS image metadata,
- user-disk descriptor readiness.

It must remain side-effect-free. It reports blockers; it does not enable Windows features, modify firmware settings, download an OS, or attempt to boot.

## Implementation Sequence

1. Native preflight: dynamically load WHP and report host/runtime blockers without linking Pane to WHP at startup.
2. Partition smoke: create a WHP partition, configure one vCPU, create that vCPU, and tear everything down cleanly.
3. Boot-to-serial spike: map guest memory and boot a controlled test kernel or minimal image far enough to emit serial output.
4. Runtime artifact boot: replace the test image with Pane's verified Arch base image and Pane user disk descriptor.
5. Storage materialization: turn the descriptor into a durable block-device format with resize, snapshot, repair, export, and import semantics.
6. Display milestone: add a Pane-owned framebuffer and input path inside the app window.
7. Integration milestone: add clipboard, file exchange boundaries, audio, resize, recovery, logging, and diagnostics.
8. Compatibility milestone: measure performance, hardware requirements, Windows feature requirements, and failure modes before exposing the native runtime as a default.

## Non-Negotiable Acceptance Gates

Pane cannot claim the native runtime is real until:

- a clean Windows machine can run `pane native-preflight` and receive actionable host checks,
- `pane native-boot-spike --execute` can create and tear down a WHP partition and vCPU without leaking resources,
- a test image can boot under a Pane-owned WHP host without WSL, XRDP, `mstsc.exe`, QEMU, VirtualBox, or Hyper-V Manager,
- Pane can boot a verified Arch base image plus a Pane-owned user disk,
- Pane renders the guest through its own app surface,
- shutdown, reset, repair, support bundles, logs, and failure recovery work without asking users to debug hypervisor internals,
- the current WSL/XRDP bridge remains clearly labeled as the fallback or legacy bridge.

## Product Implication

This is slower than shipping a wrapper around an existing VM product, but it is the path that matches Pane's stated vision. The near-term work should bias toward measurable native-runtime milestones instead of adding more distro and desktop options on top of the bridge.