[Enrique Saurez (esaurez)]

Closes #1091 (SL1.5: NVX's programs are hidden from the public API).

Stacked on #1261 (SL0.4), whose public-API snapshots this pull request updates; GitHub retargets it to dev once #1261 merges.

What and why

NVX's guest tools, managed agent, CLI and fake OpenVMM are programs, but their modules appeared in nvx's documentation as API. A binary can call only a public item, so this pull request hides the programs' entry points instead of moving them. No code moves, and every binary keeps calling the same path.

• The modules whose only public item is their entry point become #[doc(hidden)], keeping their cfgs: guest::{console_pending, device_io, exit, managed_agent, mmio_write, time_probe}, host::cli and testing, with testing::fake_openvmm. Their submodules are already private.
• guest::ingress::main, guest::time::main and guest::reseed::main become #[doc(hidden)], while the library parts beside them stay documented: Announcer, PROGRAM and StartError; TimeAbi and its types; Seed, reseed and ReseedError.
• The crate's feature list, the manifest's comments and the README's Features table say that the cli and testing features build NVX's own binaries and add no API; the crate's feature list gains the cli entry that it lacked. docs.rs's feature list doesn't change.
• The README stops linking to the hidden modules. Its module table drops the rows of nvx::testing::fake_openvmm and nvx::host::cli, with their sections, whose facts "Test hooks" and "The nvx-rs CLI" already hold, and "Test hooks" names the fake OpenVMM's source file instead of its module.
• python scripts/public_api.py --update marks the hidden items in the API snapshots.

The snapshots' diff only adds hidden markers: 20 lines of nvx-rs/public-api/linux.txt and 5 of windows.txt gain (hidden), which no line had before, and no line appears or disappears. Without the markers, both snapshots equal those of this pull request's base, line for line:

$ base=fd53cc783a93814e4d1d9cca9e0afcd7803ed563
$ for platform in linux windows; do
>   diff <(git show $base:nvx-rs/public-api/$platform.txt) \
>     <(sed 's/ (hidden)$//' nvx-rs/public-api/$platform.txt) && echo "$platform: equal"
> done
linux: equal
windows: equal

The lines that gain the marker

linux.txt:

mod nvx::guest::console_pending (hidden)
fn nvx::guest::console_pending::main (hidden)
mod nvx::guest::device_io (hidden)
fn nvx::guest::device_io::main (hidden)
mod nvx::guest::exit (hidden)
fn nvx::guest::exit::main (hidden)
fn nvx::guest::ingress::main (hidden)
mod nvx::guest::managed_agent (hidden)
fn nvx::guest::managed_agent::main (hidden)
mod nvx::guest::mmio_write (hidden)
fn nvx::guest::mmio_write::main (hidden)
fn nvx::guest::reseed::main (hidden)
fn nvx::guest::time::main (hidden)
mod nvx::guest::time_probe (hidden)
fn nvx::guest::time_probe::main (hidden)
mod nvx::host::cli (hidden)
fn nvx::host::cli::main (hidden)
mod nvx::testing (hidden)
mod nvx::testing::fake_openvmm (hidden)
fn nvx::testing::fake_openvmm::main (hidden)

windows.txt:

mod nvx::host::cli (hidden)
fn nvx::host::cli::main (hidden)
mod nvx::testing (hidden)
mod nvx::testing::fake_openvmm (hidden)
fn nvx::testing::fake_openvmm::main (hidden)

Tests

• No test changes: python scripts/check_test_changes.py --base fd53cc783a93814e4d1d9cca9e0afcd7803ed563 reports none.
• The binaries' tests and the programs' unit tests pass unchanged: nvx-rs/tests/cli.rs, with the scenario tests of nvx-rs/tests/cli/, and fake_openvmm.rs, guest_tools.rs, managed_lifecycle.rs, template_capture.rs, checked_handoff.rs, supervisor.rs and store.rs in nvx-rs/tests/; the unit tests of the hidden modules; and the guest binaries' tests (nvx.py test-guest-binaries).
• test_readme_gives_each_module_a_short_row_and_a_section (scripts/test_nvx_tools.py), which checks the README's module table, passes unchanged with the two rows fewer.

Size

0 core lines in 0 counted files, under #1076's rules: a file whose items a pull request only hides doesn't count, nor do those lines, and documentation and the snapshots don't count either. Counted as code, the 11 #[doc(hidden)] lines would make 11 core lines in 6 files: 6 in nvx-rs/src/guest/mod.rs, and 1 each in nvx-rs/src/lib.rs, nvx-rs/src/host/mod.rs, nvx-rs/src/guest/ingress/mod.rs, nvx-rs/src/guest/time/mod.rs and nvx-rs/src/guest/reseed.rs. #1091 estimated 0.

Validation

At this head. Nothing was published.

• Documentation, on Linux: cargo doc --no-deps --features cli,testing,guest with Rust 1.95.0, docs.rs's features, for docs.rs's targets x86_64-unknown-linux-gnu and x86_64-pc-windows-msvc, each into an empty documentation directory. At the base, its pages include the 8 modules and the 3 entry points that this pull request hides, for Linux, with 11 main pages in all, and host::cli and testing for Windows. At this head, it documents none of them for either target, and its list of items links to none, while the pages of the library parts remain, such as those of Announcer, PROGRAM, StartError, TimeAbi, TimeError, Seed, reseed and ReseedError.
• Public API: python scripts/public_api.py passes on Windows and on Linux. On Linux, both listings that it generates equal the committed snapshots byte for byte.
• Rust, on Windows, with Rust 1.95.0 and 1.89: the steps of check-nvx-rs that run on Windows, run as written, pass: rustfmt; Clippy, denying warnings, on every feature set, --lib --bins --features cli and --lib --bins --no-default-features --features testing included; the tests with all features and with the default ones, and the library's tests without them; the bundling test; the documentation, denying warnings; the minimum Rust version's check; and the runtime adapter's checks.
• Linux, x86-64, with Python 3.12 and the packages that requirements-dev.txt pins: the Linux-only steps of check-nvx-rs (the macOS check, the guest binaries' checks, build and tests, and the runtime adapter's guest configuration), the two --lib --bins Clippy runs, the validate-nvx unit tests (1796 tests, 39 skipped), scripts/test_adversarial.py (84 tests, none skipped), the host-connect tests, nvx.py --help for each command, the OpenVMM vector and CPU profile tests, ShellCheck, shfmt, ruff, pyright for Linux and for Windows, the Markdown links, the test layout and kernel configuration checks, and the Specula tests pass.
• Windows, with the Microsoft Store's Python 3.13 and the packages that requirements-dev.txt pins: the validate-nvx unit tests (1796 tests, 71 skipped), the host-connect tests, nvx.py --help for each command, the OpenVMM vector and CPU profile tests, ruff, pyright for Linux and for Windows, compileall, the Markdown links, the test layout, kernel configuration and PowerShell syntax checks, and the test-change check pass, and scripts/test_adversarial.py passes (84 tests, 11 skipped) with CPython 3.14.9, python.org's embeddable runtime without its ._pth file. The Specula tests fail there: they import fcntl, which Python lacks on Windows, and CI runs them on Linux only, where they pass.
• Left to CI: the full matrix, once this pull request targets dev. The change only hides items, so no VM scenarios ran.

[Copilot]

🟢 Approval recommended

No active review issues require changes.

No open issues 🎉

What changed in this PR

This PR implements SL1.5 of #1091, hiding NVX’s program entry points from generated API documentation while preserving their paths, visibility, and behavior. It builds on #1261’s public-API snapshots without hiding the library items alongside those programs.

Changes:

• Adds #[doc(hidden)] to program-only modules and three entry points in shared library modules.
• Updates feature descriptions and removes README module listings for hidden programs.
• Marks 20 Linux and 5 Windows snapshot entries as hidden, without adding or removing items.

File	Description
nvx-rs/​src/​lib.rs	Hides testing and clarifies the cli and testing features.
nvx-rs/​src/​host/​mod.rs	Hides the CLI module.
nvx-rs/​src/​guest/​time/​mod.rs	Hides the time program’s entry point.
nvx-rs/​src/​guest/​reseed.rs	Hides the reseed program’s entry point.
nvx-rs/​src/​guest/​mod.rs	Hides six program-only guest modules.
nvx-rs/​src/​guest/​ingress/​mod.rs	Hides the ingress program’s entry point.
nvx-rs/​README.md	Removes hidden-module listings and updates feature descriptions.
nvx-rs/​public-api/​windows.txt	Marks five program-related entries as hidden.
nvx-rs/​public-api/​linux.txt	Marks twenty program-related entries as hidden.
nvx-rs/​Cargo.toml	Updates comments describing program-building features; configuration is unchanged.

_{Review effort: Balanced}

[github-actions]

Neuro-formal verification (NFV) selects nontrivial properties from PR intent and source, tries verification, then tries refutation.

NFV: 0 refuted, 0 verified in PR #1265

PR head 3e0e581c270a, base 74a44fd6c162 · run and evidence

These are results for translated models under their stated assumptions, not proofs of source-code correctness or confirmed source bugs.

refuted: 0 · verified: 0 · resources exhausted: 0 · type-check/audit failure: 0

Generated by NFV PR reviewer for #1265 · ⌖ 14.2 AIC · ◷

_{Add this agentic workflow to your repo}

To install this agentic workflow, run

gh aw add microsoft/neuro-formal-verification/workflow@498aad98c39314a8c55c89dff42d771276b957d8