doc: replace doc/design with an architecture-only design guide

.github/actions/validate-runner/action.yml

@@ -167,7 +167,7 @@ runs:
           throw "Hyper-V SVGA firmware was not found: $svgaFirmware"
         }
 
-    # Host time. The time ABI host qualification (doc/design/time-abi.md,
+    # Host time. The time ABI host qualification (doc/ci.md,
     # "Host qualification") checks the backend, the CPU fingerprint and
     # generation, and the TSC rate stability on its short CI schedule, and,
     # in jobs that downloaded OpenVMM, its CPU profile check (H2) and

README.md

@@ -71,11 +71,16 @@ python scripts\nvx.py run
 
 ### Development
 
-- [Design](doc/design.md) - Current microVM architecture and ABI.
+- [Design](doc/design/README.md) - Architecture of the NVX microVM and its single-workload guest
+  runtime.
+- [Ubuntu guest support](doc/guests/ubuntu-guest.md) - How NVX runs Ubuntu userland on its own
+  kernel.
+- [Azure Linux guest support](doc/guests/azurelinux-guest.md) - How NVX runs Azure Linux userland
+  on its own kernel.
 - [Project structure](doc/project-structure.md) - Overview of the NVX repository layout.
 - [Continuous integration](doc/ci.md) - Instructions for running and maintaining NVX CI.
-- [Copilot-driven adversarial testing](doc/design/copilot-adversarial-testing.md) - Bounded
-  adaptive stress and containment campaigns.
+- [Copilot-driven adversarial testing](doc/adversarial-testing.md) - Bounded adaptive stress and
+  containment campaigns.
 - [Package and source delivery](doc/distribution.md) - Instructions for packaging and distributing
 	NVX.
 - [Contributing](doc/contribute.md) - Guidelines for contributing to NVX.

doc/design/copilot-adversarial-testing.md → doc/adversarial-testing.md

@@ -1,7 +1,5 @@
 # Copilot-driven adversarial testing
 
-[Design index](../design.md)
-
 NVX has a separate adversarial harness that uses GitHub Copilot CLI only as an
 adaptive strategist. Copilot selects deterministic guest-side probes. A typed
 broker, credential-free executor, independent watchdog, and existing microVM

doc/benchmarks.md

@@ -273,7 +273,7 @@ OpenVMM owns `BASE`; each `--cmdline` value below is appended to it. Restore pha
 command line and resume the one captured in the snapshot. OpenVMM also appends device-discovery
 tokens (`virtio_mmio.device=...` for an attached mount or NIC) and may replace `console=hvc0` with
 `console=hvc1` when a virtio console is selected. It appends no clock token: under the
-[time ABI](design/time-abi.md#rates) the NVX kernel reads the TSC and LAPIC timer rates from the
+[time ABI](design/3.2-clock-and-time.md#324-rates) the NVX kernel reads the TSC and LAPIC timer rates from the
 hypervisor identity's frequency MSRs and never calibrates either clock, and OpenVMM rejects a
 supplied `tsc_early_khz=` or `lapic_timer_hz=` token (`E_CMDLINE_CLOCK_TOKEN`). No benchmark
 command line tunes the clock or clocksource, except the `cold_start_clocksource` variant below.

doc/build.md

@@ -171,9 +171,9 @@ the static `nvx-time-probe` guest time probe, and the
 static `nvx-time` guest time component under `/sbin`. The probe measures TSC and
 clock read latency, reports the guest's clock, clocksource, TSC flags, and
 hypervisor identity, and runs the cross-vCPU warp test that the
-[time ABI](design/time-abi.md#cross-vcpu-skew-bound) uses to enforce its 1 µs
+[time ABI](design/3.2-clock-and-time.md#327-cross-processor-consistency) uses to enforce its 1 µs
 skew bound. `nvx-time` implements the time ABI's
-[guest obligations](design/time-abi.md#guest-obligations): the conformance
+[guest obligations](design/3.2-clock-and-time.md#3210-guest-obligations): the conformance
 checks, the violation watcher, the restore packet v4 and time-sample parsers,
 the snapshot agent's time steps, and the wall-clock discipline. Before
 shell-ready it only steps the clock to host UTC; the other boot checks run in
@@ -246,12 +246,12 @@ live in `KernelBuildConstants` in
 
 | Group | Required settings | Purpose |
 | --- | --- | --- |
-| Direct boot | ACPI and PVH off; MP-table parsing, local APIC, IOAPIC, and virtio-mmio devices from the command line | Boot through the [ACPI-free MP-table loader](design/cold-boot.md#linux-direct-mp-table-loader) |
-| Virtio console | Virtio console and HVC driver over virtio-mmio | Drive the [virtio consoles](design/machine-and-device-abi.md#console) |
-| Sandbox | virtio-blk; ext4; EROFS with zstd compression; overlayfs that does not always follow redirects; memory and PID cgroups; BPF and cgroup BPF; seccomp filters; Unix-domain sockets; network namespaces and veth | Layer EROFS over ext4 scratch and confine the workload in the [sandbox bootstrap](design/sandbox-filesystem-and-agent-architecture.md#implemented-filesystem-bootstrap) |
-| Network | IPv4; IPv6 without the SIT tunnel driver; virtio-net | Configure the dual-stack NIC of the [portable network profile](design/machine-and-device-abi.md#network); SIT would add an `sit0` device that decapsulates IPv6 from IPv4 packets |
-| Shared interrupt status | `CONFIG_VIRTIO_MMIO_SHARED_STATUS` from the kernel patches | Read [shared virtio interrupt status](design/machine-and-device-abi.md#fixed-virtio-mmio-transport) |
-| Time ABI | Hypervisor-guest and paravirtualization support on; Hyper-V, KVM guest, and cpufreq off | Meet the [time ABI](design/time-abi.md), as described above |
+| Direct boot | ACPI and PVH off; MP-table parsing, local APIC, IOAPIC, and virtio-mmio devices from the command line | Boot through the [ACPI-free MP-table loader](design/5.1-boot-protocol.md#511-linux-direct-loader) |
+| Virtio console | Virtio console and HVC driver over virtio-mmio | Drive the [virtio consoles](design/3.3-consoles.md) |
+| Sandbox | virtio-blk; ext4; EROFS with zstd compression; overlayfs that does not always follow redirects; memory and PID cgroups; BPF and cgroup BPF; seccomp filters; Unix-domain sockets; network namespaces and veth | Layer EROFS over ext4 scratch and confine the workload in the [sandbox bootstrap](design/4.1-guest-filesystem-and-image-model.md#411-layered-sandbox-root) |
+| Network | IPv4; IPv6 without the SIT tunnel driver; virtio-net | Configure the dual-stack NIC of the [portable network profile](design/3.5-network.md); SIT would add an `sit0` device that decapsulates IPv6 from IPv4 packets |
+| Shared interrupt status | `CONFIG_VIRTIO_MMIO_SHARED_STATUS` from the kernel patches | Read [shared virtio interrupt status](design/2.4-interrupt-and-io-architecture.md#244-shared-interrupt-status) |
+| Time ABI | Hypervisor-guest and paravirtualization support on; Hyper-V, KVM guest, and cpufreq off | Meet the [time ABI](design/3.2-clock-and-time.md), as described above |
 | Hardening | Strict kernel and module RWX with read-only executable memory, the ITS mitigation, an empty modprobe path, trimmed symbol exports, the boot-time W+X audit, and no option built as a module | Keep runtime code read-only, as described above |
 | Watchdogs | Soft-lockup and hung-task detectors off, or on in the [CI debug kernel](#ci-debug-kernel) | Keep the detectors out of production kernels |
 
@@ -284,8 +284,8 @@ the production RCU stall timeouts and turns off the debug options that
 detectors are missing from the generated config. CI can shorten the soft-lockup
 and hung-task thresholds for one boot with `watchdog_thresh=` and
 `sysctl.kernel.hung_task_timeout_secs=`. The RCU stall timeout stays at the
-production value because the time ABI's
-[conformance check C8](design/time-abi.md#conformance-checks-and-the-nvx-time-abi-marker)
+production value because the time ABI's conformance check C8, which covers
+the [stall-detector settings](design/3.2-clock-and-time.md#3210-guest-obligations),
 requires it.
 
 The variant builds in `build/linux-debug`, so it never invalidates the

doc/ci.md

@@ -35,7 +35,7 @@ one-vCPU smoke set, under the same time ABI checks; the debug-kernel jobs skip
 it, as they skip the Ubuntu tests. Failure logs from the NVX layer are uploaded
 per backend.
 Every harness launch, in the tests and the benchmarks, scans the OpenVMM
-console for the guest's [time ABI](design/time-abi.md) output, and the tests
+console for the guest's [time ABI](design/3.2-clock-and-time.md) output, and the tests
 scan every virtio console they read over TCP the same way, to its end. An
 `NVX-TIME-ABI-VIOLATION` event or a failed `NVX-TIME-ABI` conformance line
 fails the scenario at once with the guest's code and detail. Guests keep the
@@ -69,7 +69,7 @@ online CPUs after each boot or restore, in two rounds with all vCPUs halted
 for 1 s between them, so that a host without an invariant TSC corrects the
 guest TSC as idle host CPUs wake (#265). Every pair in every round must stay
 within the time ABI's 1 µs
-[cross-vCPU skew bound](design/time-abi.md#cross-vcpu-skew-bound) for both the
+[cross-vCPU skew bound](design/3.2-clock-and-time.md#327-cross-processor-consistency) for both the
 backward TSC step and the ping-pong offset; a stalled pair or an inconclusive
 measurement also fails. `smp` boots each requested processor
 count. `smp-snapshot` captures one snapshot per requested count and restores
@@ -148,11 +148,10 @@ boot, restore after a restore, and capture after `snapshot-core`'s released
 request), the exhaustive check's summary, and the
 `restore-downtime` stall counts. Where the guest reports a check's CPU time
 (`cpu_us`), the line also gives its range and how many checks exceed the
-backend's [CPU-time budget](design/time-abi.md#performance-expectations-and-acceptance-gate)
-for their phase, which the spec sets from guest measurements. The spec exempts
-the first capture after a rolled-back capture in the same VM process; CI never
-makes one, because each VM process sends OpenVMM at most one snapshot request
-and a failed capture fails its scenario.
+backend's CPU-time budget for their phase. The budgets come from guest
+measurements and exempt the first capture after a rolled-back capture in the
+same VM process; CI never makes one, because each VM process sends OpenVMM at
+most one snapshot request and a failed capture fails its scenario.
 `CHECK_CPU_BUDGET_US` in `scripts/nvx_tools/time_abi.py` holds the budgets, one
 per backend and phase. `elapsed_us` is wall time, including waits behind the
 workload, and has no budget. CI gates on neither: the performance gate is the
@@ -466,12 +465,12 @@ cache keys, and fail when a pattern misses one.
 ## Host qualification
 
 `python3 scripts/nvx.py doctor --backend <kvm|mshv|whp>` qualifies a host for
-the [time ABI](design/time-abi.md#host-qualification). It runs checks H1 to H7
+the [time ABI](design/3.2-clock-and-time.md). It runs checks H1 to H7
 in order, prints one `NVX-DOCTOR: check=<id> status=<pass|fail> detail="..."`
 line per check, and exits with status 1 if any check fails. `--checks` selects
 a subset, and `--summary` appends a Markdown table with the CPU generation,
 profile, rates, and skew metrics to a file such as `$GITHUB_STEP_SUMMARY`. H4
-and H6 run on the spec's long qualification schedules, which take about three
+and H6 run on long qualification schedules, which take about three
 minutes; `--ci-schedule` selects CI's short ones. A failure that matches a time
 ABI failure code starts its detail with the code in brackets, for example
 `[E_PROFILE_HOST_UNKNOWN]`. A check fails, and never passes, when it can't
@@ -611,7 +610,7 @@ Normal Actions artifacts contain only the guest-text-free public summary,
 catalogued case identifiers, and replay manifest. The external provisioner
 must collect controller transcripts and complete target logs into
 access-controlled security storage. See
-[Copilot-driven adversarial testing](design/copilot-adversarial-testing.md)
+[Copilot-driven adversarial testing](adversarial-testing.md)
 for the architecture and operational contract.
 
 ## Copilot environments

doc/contribute.md

@@ -108,7 +108,7 @@ mechanics, such as the golden fixtures of the control protocol, belong in
 `nvx-rs`, and tests of the ACI Edge Sandboxes contract in
 `aci_edge_sandboxes`. The `scripts/nvx.py test-aci-edge-sandboxes --backend
 BACKEND` command runs all ignored `openvmm_e2e` tests on a real hypervisor,
-which exercises both crates. [Validation](design/validation.md)
+which exercises both crates. [Continuous integration](ci.md)
 describes what the OpenVMM VMM tests and the NVX microVM suite cover.
 
 ## OpenVMM

doc/design/1-architecture-overview.md

@@ -0,0 +1,42 @@
+# Architecture Overview
+
+[Architecture documentation](README.md)
+
+NVX provides a small, versioned virtual machine for running Linux workloads on Linux or Windows
+hosts (Figure 1.1). The guest-visible machine is owned by the NVX machine profile rather than
+inferred from the selected hypervisor. KVM, MSHV, and WHP provide execution services, while the
+machine profile defines one common boot, CPU, memory, device, time, and lifecycle contract.
+
+This chapter introduces NVX's purpose, major architectural elements, trust boundaries, and
+compatibility principles.
+
+```mermaid
+flowchart TB
+   Host["Host Orchestrator<br/>configuration, policy, and attachments"]
+   Vmm["OpenVMM NVX Machine Profile<br/>machine, devices, and lifecycle"]
+   Backend["Execution backend<br/>KVM, MSHV, or WHP"]
+   Guest["Guest kernel and guest agents<br/>boot, repair, and supervision"]
+   Workload["Single isolated workload"]
+   Artifacts["Immutable snapshot artifacts<br/>and external attachments"]
+
+   Host --> Vmm
+   Vmm --> Backend
+   Vmm <--> Guest
+   Guest --> Workload
+   Vmm <--> Artifacts
+```
+
+**Figure 1.1.** High-level view of the NVX architecture.
+
+## Table of Contents
+
+- [1.1 Goals](1.1-goals.md): Defines the properties the architecture provides.
+- [1.2 Non-Goals](1.2-non-goals.md): Identifies the concerns outside the
+  architecture's scope.
+- [1.3 System Components and Responsibilities](1.3-system-components-and-responsibilities.md):
+  Identifies the host, VMM, and guest components and assigns responsibility to
+  each.
+- [1.4 Trust Boundaries](1.4-trust-boundaries.md): Describes trusted and
+  untrusted actors, sensitive data flows, and validation boundaries.
+- [1.5 Compatibility and Versioning Model](1.5-compatibility-and-versioning-model.md):
+  Explains how guest-visible contracts and persisted state evolve.

doc/design/1.1-goals.md

@@ -0,0 +1,16 @@
+# 1.1 Goals
+
+[Architecture documentation](README.md) >
+[1. Architecture Overview](1-architecture-overview.md)
+
+The architecture has the following goals:
+
+- Boot the same uncompressed Linux-direct kernel on Linux and Windows hosts.
+- Keep the guest-visible machine independent of the selected hypervisor.
+- Expose only a fixed, allowlisted set of devices.
+- Capture a running VM into immutable artifacts that can be restored in a new
+  process without serializing native host handles.
+- Run exactly one workload per microVM.
+- Assemble the workload filesystem from an immutable image layer, private
+  writable scratch, and optional live host shares.
+- Keep workload policy and host-resource attachment under host control.

doc/design/1.2-non-goals.md

@@ -0,0 +1,22 @@
+# 1.2 Non-Goals
+
+[Architecture documentation](README.md) >
+[1. Architecture Overview](1-architecture-overview.md)
+
+The architecture deliberately excludes:
+
+- Firmware boot, caller-defined ACPI and SMBIOS tables or device trees, PCI, vPCI, VMBus, and
+  arbitrary devices.
+- SMT, multiple NUMA nodes, non-x86 guests, and nested virtualization.
+- General CPU or memory hotplug after readiness.
+- Restore across hypervisor backends or CPU generations, live migration, and
+  capture-and-continue.
+- Scaling of the TSC, trapping of RDTSC, paravirtual clocks, and a virtual PMU.
+- Serialization of live network flows, native host handles, or the contents of
+  a live host filesystem export.
+- Multi-container orchestration, including pod infrastructure, pause
+  containers, dynamic root filesystem injection, and host calls that create
+  additional containers.
+- Confidential computing, because the host is trusted with image content and
+  guest memory.
+- Tenant authorization inside the VMM.