nvx-rs slimming 1.1.1: the public API is checked, and NVX's programs are hidden from it #1091

Parent: #1077, in #1076. Needs: —. Unblocks: #1097, #1098, #1099, #1101, #1104, #1115, #1120, #1131, #1132.

Goal. CI records nvx's public API in committed Linux and Windows snapshots, then hides NVX's programs from that API without moving them. Each binary keeps calling its current #[doc(hidden)] pub fn main; program-only modules become hidden, while library items beside a program stay documented. The cli and testing features keep building NVX's own programs and add only hidden entry points. CI also denies warnings in builds of cli alone and of testing alone, so that the compiler checks the private code of every feature set.

Notes.

• The snapshot comes first. SL0.4 records today's API without changing it; SL1.5 then updates only the hidden markers.
• Nothing moves. Every binary, module and source file stays at its current path, and program behavior stays unchanged.

PRs, in order. Each PR has one goal, leaves dev green, and names in its description each old test of its area as kept, rewritten or retired, with each change that check_test_changes.py reports. Its tests follow the repository's test layout: a module's unit tests, and the code that only they use, sit in its tests.rs or tests/ and move with it. The estimates count core lines (code, not comments, docs or tests) and counted files; each PR records its measured values. Each PR does what its Scope says and no more: a case, input or layout that its Scope doesn't name, and whatever "Not in this PR" lists, is out of scope. Address every review comment within the scope, and ask before acting on one that asks for more. A PR whose measured core lines pass the stop that its Estimate names (twice the estimate, at most 600) stops and asks before continuing.

1. SL0.4: The public API has a checked snapshot.

   • Objective: Nothing records which items nvx exposes, so a PR can widen or narrow the public API unnoticed, and the work that follows makes many items private. This PR commits a snapshot of the public API, with hidden items marked, and makes CI fail when the code and the snapshot differ, so each later PR shows its API change in its diff.
   • Contents: scripts/public_api.py, with its tests: it builds the library's rustdoc JSON on the pinned toolchain (RUSTC_BOOTSTRAP=1, -Z unstable-options --output-format json --document-hidden-items), with every feature but bundled, for Linux (the guests' target) and Windows; lists every public item by kind and path (modules, types, traits, functions, constants, statics, type aliases, macros, fields, variants, methods and associated items, not trait implementations), marking those that #[doc(hidden)] hides; and compares the lists with nvx-rs/public-api/linux.txt and windows.txt, which --update rewrites. CI's check runs it and prints the difference. It reads only the pinned toolchain's JSON format. CI's check also denies warnings in builds of cli alone and of testing alone, which it doesn't build today, so that the compiler checks the private code of each feature set.
   • Scope:
     • scripts/public_api.py builds rustdoc's JSON for the library on the pinned toolchain, with RUSTC_BOOTSTRAP=1 and --document-hidden-items, enabling every feature but bundled, for Linux (the guests' target) and for Windows.
     • It walks the public tree from the crate root, following re-exports, and writes one sorted line per item: its kind, its path, and whether #[doc(hidden)] hides it or a hidden module contains it.
     • Its items are modules, types, traits, functions, constants, statics, type aliases, macros, public fields, variants, inherent methods and associated items; trait implementations are left out.
     • nvx-rs/public-api/linux.txt and windows.txt hold today's lists; --update rewrites them, and the check mode prints the difference and fails.
     • CI's check runs the comparison, and scripts/test_public_api.py tests the walk on small JSON fixtures: re-exports, hidden modules, feature-gated items and an unknown format version.
     • CI's check also runs clippy, denying warnings, with --features cli and with --no-default-features --features testing, beside its current feature sets; both pass on today's code.
   • Not in this PR:
     • Changing any visibility or hiding anything: the snapshot records today's API as it is, and later PRs change it.
     • Comparing the API with the planned final surface: the release checks that.
     • Trait implementations, auto traits, signatures or semver analysis: the lists name items only.
     • Support for other toolchains' JSON formats, or a new Cargo tool dependency.
   • Approach: Run cargo rustdoc --lib with the unstable JSON output on the pinned toolchain, once per platform's target, and walk the JSON index from the root module, resolving use items to their targets and carrying a hidden flag down from hidden modules. Keep the output plain text, one item a line, sorted, so that a diff reads like the API change. Refuse a format version other than the pinned toolchain's. Add the two feature builds as plain commands of the existing check action.
   • Done when:
     • CI fails when a public item is added, removed or hidden without its snapshot changing, and passes when they agree.
     • The committed snapshots list today's public API on Linux and on Windows, with the hidden items marked.
     • --update rewrites the snapshots, and the script's tests pass in CI.
     • CI denies warnings for --features cli and for --no-default-features --features testing.
   • Needs: nothing.
   • Estimate: 250 core lines, 3 counted files. Past 500 core lines, stop and ask before continuing.

2. SL1.5: NVX's programs are hidden from the public API.

   • Objective: NVX's guest tools, managed agent, CLI and fake OpenVMM are programs, but their modules appear in nvx's documentation as API. A binary can only call a public item, so this PR hides the programs' entry points instead, without moving code or changing any binary, and the API snapshot records them as hidden.
   • Contents: Each binary keeps calling its entry point where it is, now #[doc(hidden)]: guest::{console_pending, device_io, exit, mmio_write, time_probe, managed_agent}, host::cli and testing (with testing::fake_openvmm), whose only public items are their main, become #[doc(hidden)] modules; ingress::main, time::main and reseed::main become #[doc(hidden)], beside the library parts that stay public (Announcer, PROGRAM, StartError; TimeAbi and its types; Seed, reseed, ReseedError). The crate's feature list and the README say that the cli and testing features build NVX's own binaries and add no API. The API snapshot marks the entry points hidden.
   • Scope:
     • guest::{console_pending, device_io, exit, mmio_write, time_probe, managed_agent}, host::cli and testing, whose only public items are their entry points, become #[doc(hidden)] modules.
     • ingress::main, time::main and reseed::main become #[doc(hidden)]; Announcer, PROGRAM, StartError, TimeAbi with its types, Seed, reseed and ReseedError stay documented.
     • The crate's feature list and the README say that the cli and testing features build NVX's own binaries and add no API, and stop linking to the hidden modules.
     • The API snapshot marks the entry points and their modules hidden.
   • Not in this PR:
     • Moving, renaming or splitting any program, binary or module: every binary keeps calling the same path.
     • Making any other item private or hidden: later PRs do that, one area each.
     • Removing or renaming the cli and testing features, or changing docs.rs's feature list.
     • Changing a program's behavior, output or exit status.
   • Approach: Add #[doc(hidden)] to each program module's declaration, or to main where a library part shares the module; their submodules are already private, so nothing else changes. Regenerate the API snapshot with scripts/public_api.py --update, and check that its diff only adds hidden markers.
   • Done when:
     • Every binary builds and runs as before, and its tests pass unchanged.
     • cargo doc with docs.rs's features shows none of the programs' modules or entry points.
     • The API snapshot's diff only adds hidden markers: no item appears or disappears.
   • Needs: SL0.4, above.
   • Estimate: 0 core lines (visibility), no counted files.

Tests. The API script builds rustdoc JSON for Linux and Windows with every feature but bundled, follows re-exports, marks hidden modules and items, and fails with a readable difference when a snapshot is stale. Its fixture tests cover re-exports, hidden modules, feature-gated items and an unknown JSON format. Every binary builds and its existing command-line, output and exit-status tests pass unchanged. Rustdoc shows the library parts but none of NVX's program modules or entry points, and the snapshot's second diff only adds hidden markers. The cli-only and testing-only builds pass without warnings.

Done when: every PR above has merged, with dev green.