time ABI: retarget citations of the removed specification and rehome its reference detail #562

Summary

#529 replaced doc/design/ with the architecture guide and removed doc/design/time-abi.md, the time ABI specification. The guide keeps the time ABI's guest-visible contract, in 2.2 (CPU profiles), 3.2 (clock and time), and 5.5 (restore packet and guest repair), but by design leaves out the specification's reference detail. NVX code, tests, and documentation still cite "the spec" for that detail, and three OpenVMM module comments still cite the removed file by path.

Why

• Dangling citations. The comments, docstrings, and the doctor's --checks help text ("in spec order") refer to a document that now exists only in history, as 19a359bb3:doc/design/time-abi.md.
• Reference detail without a home. No document now describes the guest's violation codes (G_*), the conformance checks that doc/build.md and doc/ci.md cite by ID (C3, C8, and C11), the formats of the NVX-TIME-ABI lines, or the keys of the state file, /run/nvx/time/state. The OpenVMM Guide describes many host-side failure codes where they arise, in Guide/src/user_guide/openvmm/snapshots.md and Guide/src/reference/openvmm/management/cli.md, but no document lists them, although OpenVMM and the doctor report failures by code.
• Spec-derived tests without a specification. scripts/test_guest_time.py encodes its fixtures independently of the C decoders, to check the guest against the specification. Its restore packet and time sample now follow the guide (5.5.5 and 3.2.9), but its exhaustive-check lines and state file follow sections that no document holds any more.

What the citations point to

Sections of the removed specification that the code cites and the guide leaves out:

• "Failure codes": the E_* codes, with their meaning and the phases that raise them.
• "Conformance checks and the NVX-TIME-ABI marker": checks C1 to C12, the CI-only exhaustive checks X1 to X6, and the line formats.
• "Violation watcher": the G_* codes and the kernel messages that raise them.
• "Wall-clock discipline": the state file.
• "Cross-vCPU skew bound": the backward step and ping-pong offset that the 1 µs bound applies to.
• "Performance expectations and acceptance gate": the CPU-time budgets, now only in CHECK_CPU_BUDGET_US in scripts/nvx_tools/time_abi.py.
• "Test matrix": the cases that the microVM scenarios implement, such as the long-downtime restore.

Where the specification is cited

Line numbers are at cc9960f.

NVX:

• guest/common/nvx-time.c: lines 189, 836, and 992.
• scripts/nvx_tools/doctor.py: lines 904 and 1018, and the --checks help text at line 1146.
• scripts/nvx_tools/time_abi.py: lines 103 and 962.
• scripts/nvx_tools/microvm_tests.py: lines 145 and 305.
• scripts/test_guest_time.py: the module docstring, and lines 50, 67, 589, and 737.
• scripts/test_time_abi.py: lines 759, 771, and 775.
• doc/build.md: conformance check C8, at line 287.

OpenVMM (the openvmm/ submodule at 7f225e2cd; paths relative to it):

• vmm_core/virt/src/time_abi/mod.rs: "The contract is specified in the NVX repository, doc/design/time-abi.md."
• vmm_core/virt_kvm/src/arch/x86_64/time_abi.rs and vmm_core/virt_whp/src/time_abi.rs: each implements its backend's column of "Backend obligations" in that file. Section 3.2.6 of the guide lists the obligations once for every backend, without per-backend columns, so these comments need rewording, not only a new path.

Decisions

• Where the reference detail lives. One of:
  • A time ABI reference outside the architecture guide, such as doc/time-abi.md, restored from the removed specification without what the guide now covers.
  • The OpenVMM Guide for the host-side codes and outputs, which it already partly describes, with nvx-time.c and its tests defining the guest-side formats.
  • No reference: each comment states its own facts, and the tests stop claiming an independent specification.
• Test oracle. Decide what the fixtures of scripts/test_guest_time.py derive from where the guide defines no format.

Tasks

• Decide where the reference detail lives, and document there the codes and check IDs that users meet.
• Retarget or reword every NVX citation above, including the doctor's --checks help text.
• OpenVMM: retarget the three module comments to doc/design/3.2-clock-and-time.md, citing 3.2.6 from the backends, or to the reference. They are documentation only, so fold them into the next OpenVMM change to these crates rather than a pin promotion of their own.
• NVX: promote the OpenVMM pin.