nvx-rs: pin the wire formats with versioned conformance vectors

.github/skills/nvx-openvmm-promote/SKILL.md

@@ -86,8 +86,22 @@ git diff --name-only
 git diff --check
 ```
 
+`nvx-rs`'s protocol tests read copies of OpenVMM's control-session protocol vectors.
+Compare them with the revision's files, as the NVX CLI jobs do:
+
+```console
+cargo test --locked --manifest-path nvx-rs/Cargo.toml --no-default-features --test openvmm_vectors -- --ignored
+```
+
+A failure means that the revision changes the `NVXS` vectors that NVX's host and guest
+must follow. Copy both files unchanged into `nvx-rs/tests/vectors/openvmm/`, record the
+revision in [the vectors' README](../../../nvx-rs/tests/vectors/README.md#openvmms-vectors),
+and run the `nvx-rs` tests, which may need coordinated changes too.
+
 Before committing, require `git diff --name-only` to contain exactly `openvmm`
-unless coordinated NVX changes were explicitly requested. Stage only the gitlink.
+unless coordinated NVX changes were explicitly requested, or the revision needs them,
+as a change to OpenVMM's protocol vectors does. Stage only the gitlink and those
+changes, and name the coordinated changes in the pull request.
 Commit only when the user requested it. Follow the repository's subject convention,
 sign the commit with the user's existing configuration, and stop rather than falling
 back to an unsigned commit if signing fails. Never amend, force-push, or rewrite an
@@ -153,5 +167,6 @@ head SHA matches the current pull-request head. Treat older runs as superseded a
 ## Report
 
 Report the source PR and revision, signature result, dependency state, equivalence
-method and result, NVX target commit, final changed-file set, local validation, pull-
-request state and URL, exact-head workflow URL, and every blocked or pending gate.
+method and result, NVX target commit, final changed-file set, local validation, the
+comparison of OpenVMM's protocol vectors, pull-request state and URL, exact-head
+workflow URL, and every blocked or pending gate.

.github/workflows/ci.yml

@@ -160,6 +160,15 @@ jobs:
       - name: Validate NVX CLI
         uses: ./.github/actions/validate-nvx
 
+      # nvx-rs's protocol tests read copies of OpenVMM's control-session
+      # protocol vectors, because the nvx-rs job cannot check out OpenVMM.
+      # This job can, so it compares the copies with the submodule's files.
+      - name: Compare OpenVMM's protocol vectors
+        shell: bash
+        run: >-
+          cargo test --locked --manifest-path nvx-rs/Cargo.toml
+          --no-default-features --test openvmm_vectors -- --ignored
+
       - name: Upload nvx-rs executable
         uses: actions/upload-artifact@v7
         with:
@@ -248,6 +257,15 @@ jobs:
       - name: Validate NVX CLI
         uses: ./.github/actions/validate-nvx
 
+      # As on Linux.
+      - name: Compare OpenVMM's protocol vectors
+        shell: powershell
+        run: |
+          $ErrorActionPreference = "Stop"
+          cargo test --locked --manifest-path nvx-rs/Cargo.toml --no-default-features `
+            --test openvmm_vectors -- --ignored
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+
       - name: Upload nvx-rs executable
         uses: actions/upload-artifact@v7
         with:

aci_edge_sandboxes/README.md

@@ -1057,7 +1057,7 @@ runs, stages a synthetic agent bundle through `ACI_EDGE_SANDBOXES_AGENT_BUNDLE_D
 bundled-agent tests must find, and checks that the build rejects broken copies of it; it needs
 neither a hypervisor nor an agent library that runs. The NVX
 mechanics are tested in [`nvx-rs`](../nvx-rs/README.md)
-as well, with their own unit tests, golden protocol fixtures, and a
+as well, with their own unit tests, protocol conformance vectors, and a
 fake-OpenVMM lifecycle test.
 
 - `testing::MockBackend` scripts executions for consumers' unit tests.

doc/ci.md

@@ -539,6 +539,10 @@ the Windows job also installs the pinned Rust release with the minimal profile
 for the curl shim test and the `nvx-rs` build. Each job first builds the
 `nvx-rs` executable that `nvx.py` runs, tests with it, and hands it to the
 microVM test and platform jobs of its operating system, as described above.
+Each also runs the ignored `nvx-rs` test `tests/openvmm_vectors.rs`, which
+compares the submodule's control-session protocol vectors with the copies that
+the protocol tests read in the `nvx-rs` job, which cannot check out OpenVMM;
+see [OpenVMM's vectors](../nvx-rs/tests/vectors/README.md#openvmms-vectors).
 Fork pull requests lack the OpenVMM deploy key, so the CLI jobs run, like the
 hypervisor jobs, only for pushes, full runs, and same-repository pull requests.
 Because the microVM and platform jobs of each operating system wait for its CLI
@@ -1487,10 +1491,10 @@ The required `nvx-rs` job checks the [`nvx` crate](../nvx-rs/README.md),
 which holds the NVX mechanics that the backend builds on, on the same runners
 through the [`check-nvx-rs`](../.github/actions/check-nvx-rs/action.yml)
 action. It runs rustfmt, Clippy with warnings denied for all targets and
-features and for the library without default features, the unit, golden
-protocol-fixture, and fake-OpenVMM instance tests, rustdoc with warnings
-denied, the minimum Rust version check, and the macOS cross-check. It also
-validates bundled artifact staging with a fixture package. Both actions set
+features and for the library without default features, the unit, protocol
+conformance-vector and property, and fake-OpenVMM instance tests, rustdoc with
+warnings denied, the minimum Rust version check, and the macOS cross-check. It
+also validates bundled artifact staging with a fixture package. Both actions set
 `NVX_BUNDLE=skip` for `--all-features` builds, so that `bundled` stages nothing
 instead of downloading the pinned release, and the `aci_edge_sandboxes` action
 also sets `ACI_EDGE_SANDBOXES_AGENT_BUNDLE=skip`, so that `agent-bundled` does

doc/contribute.md

@@ -78,7 +78,7 @@ the Python, shell, and link checks.
 | `aci_edge_sandboxes/` | rustfmt, Clippy and rustdoc with warnings denied, tests, and the minimum supported Rust version; see [Rust crates](ci.md#rust-crates) | [check-aci-edge-sandboxes](../.github/actions/check-aci-edge-sandboxes/action.yml) |
 | `nvx-rs/` | rustfmt, Clippy and rustdoc with warnings denied, tests including a bundled-release fixture, the minimum supported Rust version, a macOS check, and, through `nvx.py`, the musl lint, tests, build, digest manifest, and static-ELF check of the guest binaries; see [Rust crates](ci.md#rust-crates) | [check-nvx-rs](../.github/actions/check-nvx-rs/action.yml) |
 | `tests/runtime-adapter/` | rustfmt, then Clippy with warnings denied, the build, the tests, and the minimum supported Rust version of `nvx`, in the protocol-only, host-only, and, on Linux, static musl guest-only configurations; see [Rust crates](ci.md#rust-crates) | [check-nvx-rs](../.github/actions/check-nvx-rs/action.yml) |
-| NVX CLI | Compiles `scripts/`, runs every `scripts/test_*.py` module, and checks command help, on Linux and Windows | [validate-nvx](../.github/actions/validate-nvx/action.yml) |
+| NVX CLI | Compiles `scripts/`, runs every `scripts/test_*.py` module, and checks command help, on Linux and Windows, and compares the copies of OpenVMM's protocol vectors in `nvx-rs/tests/vectors/openvmm/` with the submodule's files | [validate-nvx](../.github/actions/validate-nvx/action.yml), [ci.yml](../.github/workflows/ci.yml) |
 
 check-quality names each shell script that it checks, and a CLI test fails
 unless validate-nvx runs every `scripts/test_*.py` module on both operating
@@ -115,9 +115,12 @@ Unit tests for the host tooling live in `scripts/test_*.py`. The
 `aci_edge_sandboxes` and `nvx` crates keep unit tests alongside their Rust
 source and integration tests in their `tests` directories. The latter also
 runs `tests/guest_tools.rs` against the exact guest-profile binaries. Tests of the NVX
-mechanics, such as the golden fixtures of the control protocol, belong in
+mechanics, such as the conformance vectors of the control protocol, belong in
 `nvx`, and tests of the ACI Edge Sandboxes contract in
-`aci_edge_sandboxes`. Tests of what an independent adapter observes through
+`aci_edge_sandboxes`. The vectors, in
+[`nvx-rs/tests/vectors/`](../nvx-rs/tests/vectors/README.md), are bytes that
+no codec produced: change one only with a protocol version, which gets vector
+files of its own. Tests of what an independent adapter observes through
 the public API of `nvx` alone, such as its own framing over the control
 session between the host and the guest, belong in the
 [runtime adapter](../tests/runtime-adapter/README.md), whose ignored tests the
@@ -164,6 +167,11 @@ A pin promotion moves the `openvmm` gitlink to a reviewed OpenVMM revision:
   to host CPU profiles`. Never merge OpenVMM history into NVX.
 - After committing, run `scripts/nvx.py verify`, which checks that the
   submodule checkout matches the recorded pin.
+- `nvx-rs` checks copies of OpenVMM's control-session protocol vectors, which
+  the NVX CLI jobs compare with the submodule's files. When a revision changes
+  them, copy them into `nvx-rs/tests/vectors/openvmm/` unchanged and record the
+  revision, in the same commit; see
+  [OpenVMM's vectors](../nvx-rs/tests/vectors/README.md#openvmms-vectors).
 - In the pull request, name the OpenVMM pull request and the exact pinned
   SHA, the scope and any prerequisite revisions, and the validation you ran.
 - A gitlink change is an input of every CI suite, so its pull request runs

doc/design/3.5-network.md

@@ -179,7 +179,10 @@ capabilities, cannot bind, so the workload cannot forge an announcement. An
 announcement carries a magic value, a version, a flag that marks omitted
 listeners, and at most 64 entries in strictly increasing order of protocol and
 port, each naming the protocol, TCP or UDP, the address families, and the
-port. The endpoint consumes announcements before the egress policy, which
+port; the conformance vectors of version 1, in
+[`nvxl-v1.txt`](../../nvx-rs/tests/vectors/nvxl-v1.txt), give the bytes of
+announcements that the guest agent sends and the endpoint accepts. The
+endpoint consumes announcements before the egress policy, which
 neither authorizes nor forwards them, and each announcement replaces the
 published set. For each published port and address family, the endpoint keeps
 one host listener at the guest's port number:

doc/design/4.4-host-guest-control-interface.md

@@ -115,3 +115,16 @@ Secrets and per-execution environments belong on the authenticated control
 channel, not in the kernel command line, image layers, scratch, or snapshot
 metadata. Boot configuration that the machine profile owns contains only the
 non-secret invariants needed before the control channel exists.
+
+## 4.4.4 Conformance Vectors
+
+Conformance vectors give the bytes that every host and guest agent must
+produce and accept, whatever code they share.
+[`nvxc-v1.txt`](../../nvx-rs/tests/vectors/nvxc-v1.txt) holds those of
+version 1 of the control protocol: its frames, their execution, mapping, and
+feature payloads, and records of the session that carries them.
+[`openvmm/`](../../nvx-rs/tests/vectors/openvmm) holds the VMM's own vectors
+and cases of the session's records, unchanged. A vector changes only with a
+protocol version, which gets vector files of its own, and the bytes of an
+earlier version that it refuses become its rejection vectors. The vectors'
+[README](../../nvx-rs/tests/vectors/README.md) describes their line format.

doc/project-structure.md

@@ -110,7 +110,7 @@ nvx/
 |   |   |-- testing/             Fake OpenVMM (feature `testing`)
 |   |   |-- guest/               Programs that run in Linux guests, the guest's NVXS connection, the libraries through which any guest init or agent opens the terminal on which it serves its session, starts a program, collects its children's statuses, settles its executions' cgroups, drives each execution, mounts host mappings beneath the descriptors of the roots that it names, assembles and tears down a layered root, and reads a GPT disk's partition table through its block device, and the typed calls through which it runs the time ABI's steps and the reseed (feature `guest`)
 |   |   `-- bin/                 nvx-rs CLI, nvx-fake-openvmm test double, and the guest binaries
-|   |-- tests/                   Fake-OpenVMM instance lifecycle, sandbox store, CLI, NVXS session, guest-binary, and hypervisor managed-lifecycle tests, the store's record fixtures, and the golden fixtures that Python recorded
+|   |-- tests/                   Fake-OpenVMM instance lifecycle, sandbox store, CLI, NVXS session, guest-binary, and hypervisor managed-lifecycle tests, the store's record fixtures, the golden fixtures that Python recorded, and the conformance vectors of the wire formats
 |   |-- build.rs                 Stages the bundled artifacts (feature `bundled`)
 |   `-- artifacts.json           Release package pinned for the bundled artifacts
 |-- openvmm/                     OpenVMM Git submodule

nvx-rs/Cargo.toml

@@ -96,6 +96,9 @@ serde_json = { version = "1.0.120", optional = true }
 sha2 = { version = "0.10", optional = true }
 
 [dev-dependencies]
+# The property tests of the protocol's codecs, which need none of the forking and timeouts of its
+# default features.
+proptest = { version = "1.12.0", default-features = false, features = ["std"] }
 serde_json = "1.0.120"
 tempfile = "3.10"