[Pedro Henrique Penna (ppenna)]

Part of #1130 (SL6.10a, "The library's guide describes only the final public library"). Parent #1090, umbrella #1076.

What and why

The landing page and the crate README still presented nvx as "the NVX mechanics" with the supervision of NVX's microVMs, laid out the split platform, store and supervisor modules, listed exec among the modules without default features, kept an uncompiled copy of lib.rs's example, and gave modules that leave the public API, or the crate, rows and long sections of their own. Nothing told a program that uses the library what it owns now that the library keeps no stores, drives no restore and applies no path or image rules. This PR does SL6.10a's Scope and no more, and describes the final public library, which feature/nvx-refactor now holds: the host chain (SL6.6c, SL6.7b, SL6.6d, SL6.5a2, SL6.5b, SL6.8c), SL6.11b (#1542), SL6.14, SL4.4b, SL6.11d (#1547), SL6.13b (#1548), SL4.4c (#1541) and SL4.4d (#1545) have merged. Each statement was checked against the code of the tip that this branch is restacked on.

• doc/library.md (new, the one guide): a host program's three workflows, each linked to code that CI compiles through the public API alone rather than a copy of it:
  • Cold boot: vm::create_private_dir, VmDir::open, vm::create, vm::spawn (or Prepared::into_command for a launcher of the caller's own), transport::connect_verified and HostConnection::attach, vm::stop. Linked: the example of the crate documentation in nvx-rs/src/lib.rs (a rustdoc test), cold_boot and stop in nvx-rs/examples/host-workflows.rs (compile-only), and external-launch.
  • Restore from a strict snapshot, with the capture that makes one: finish_capture, Snapshot::open, the caller's per-snapshot lock on Linux, vm::create(.., Some(&snapshot), ..), Prepared::activation_record, a RestoreMachine that the program drives with its own I/O, and the guest's Activation. Linked: capture and restore in host-workflows, capture and activate in guest-workflows.
  • Reattach after a restart: SavedVm, vm::reattach, vm::verify, RuntimeMismatch. Linked: reattach in host-workflows, and the rustdoc test of host::transport.
  • What the caller owns, in bounded lists, in place of the removed stores, clone driver and path and image rules: paths and image checks, durable state, locks, I/O, timing, recovery, outputs and process lifecycle, each from the rustdoc and code of host::{vm, snapshot, restore, filesystem, transport, process} (for example the Linux per-snapshot lock, the Windows spawn's inheritance window and windows_breakaway, ExportPlan's paths-only race and rechecks, RestoreError's attribution, StillRunning).
• nvx-rs/README.md, slimmed to the final public library:
  • The intro names the library's mechanisms and what it leaves to its users, links the guide and the guest-agent guidelines, and names NVX's programs, NVXC and the code that only they use as private users of the library, whose binaries call hidden mains. Features come first (exec gone).
  • The layout's tree and the module table describe the final public modules: guest::{exec, spawn, process, cgroup, entry} are gone; guest::{root, view, gpt}, the mapper and an activation's application are nvx-init's space, private to the crate, which a short nvx-init's space section under the guest binaries describes and the guidelines detail; host::platform is private and host::report a module of its own; nvx::protocol::maps and nvx::Error gain rows. The table keeps the convention of .github/copilot-instructions.md: 36 rows, each one line of at most 200 characters that links its section after the table, above the floor of 30 that guest: delete the process modules and cgroups (SL6.11b) #1542 set (test_readme_gives_each_module_a_short_row_and_a_section). It lists no private module.
  • The module sections keep each module's contracts and leave the rest to the rustdoc; the paragraph on the split platform, store and supervisor layout goes. nvx::protocol says that NVXC is private and speaks version 2 alone, as SL4.4c and SL4.4d make it; ExportPlan holds paths only; nvx::Error has no public codes or constructors, and library callers tell errors apart by their kinds alone (the old text also had them match message fragments, which Error's rustdoc reserves to the CLI's callers). The uncompiled Example gives way to the guide.
  • The CLI's sections (Egress policy files through Scenario tests), the table of error codes, the binaries' table and Testing keep their places, since other documents link them (doc/usage.md, doc/ci.md, doc/contribute.md, doc/build.md, doc/distribution.md, the repository instructions) and SL6.10d owns the CLI reference, but no longer say what the code stopped doing: the security checklist covers a VM's directory and outputs and a snapshot's directory, while the checks of an export's targets, read-only paths and owner, and of its exported objects, are unit tests of host::filesystem (the finding that SL6.10f's agent reported); the store's runtime record is strict and has no format, so an earlier build's record fails every transition as one that does not parse; the deleted sandbox plan no longer holds the network policy; a configuration that nvx.py wrote fails as an unsupported format; a RAM upper records no scratch binding; format-unsupported and foreign-files name the state that the CLI still keeps, not a started sandbox's runtime record or the deleted template store; still-running and StillRunning also follow a failed spawn; and the news of an API change of the now private host::sandbox goes.
• README.md: the landing page's note on integration and its usage list link the guide, its crate entry describes the library and NVX's programs in it, and the guest-agent guidelines join the list. No other root section changes.

Restack. After SL6.8c merged, the branch was restacked with git rebase --onto origin/feature/nvx-refactor 5d18353131d, with rerere off. The guide and the landing page applied as they were. The README's conflict was resolved by section: this slim structure for the library part, and the tip's text, with SL4.4c's, SL4.4d's and SL6.13b's edits, for the sections kept above; then every statement was checked against the tip. The private space's long sections, which SL6.13b moved under nvx-init's space, give way to the short section above, since the guidelines give the space's interface. The fixes' autosquash then moved the base to e6c65b95f63, which adds SL6.10e's docs and touches none of these files. At the tip's floor of 30, test_readme_gives_each_module_a_short_row_and_a_section passes.

Case matrix. No test changes. Its Docs row for the README's Example already records the fate (rewritten; "the library's guide (SL6.10a) replaces the example"), so no row changes.

Not in this PR, per #1130: CLI reference material (SL6.10d), design pages (SL6.10b, SL6.10c), other guides or a cookbook, build and CI docs (SL6.10e, SL6.10f), the rustdoc (SL6.10g), the migration guide (SL6.10h), and examples beyond cold boot, restore and reattach.

Size. 0 core lines and 0 counted files (estimate 0): two READMEs and one new guide. BOOT_CONTRACT_VERSION, CONTROL_CONTRACT_REVISION and the public API are unchanged.

Validation

local_gates.py (dev's) selects markdown-links, test-layout, test-changes, the nvx-rs checks and validate-nvx for these files; the ones that the change affects ran from this branch's action definitions, on Windows, at 506524fa2b7 on e6c65b95f63, unless a row says otherwise; Copilot's later finding changed one sentence of the guide, after which the link check passed again at faad27c788e:

Check	Result
python scripts/check_markdown_links.py	Passed, and at each of the three commits before the restack (git rebase --exec)
python scripts/check_test_layout.py	Passed
python scripts/check_test_changes.py --base origin/feature/nvx-refactor	0 changes to existing tests
cargo test --locked --lib --manifest-path nvx-rs/Cargo.toml -- error::tests (reads the README's error codes through include_str!)	5 passed
python -m unittest test_nvx_tools.NvxRsTests test_markdown_links test_tool_versions, which include the module table's test at the tip's floor of 30 and the error codes against doc/usage.md	137 passed
validate-nvx (Windows): compileall and the unittest list	At the restack, d368e666fb5 on 12a90c4a0ee, before the prose fixes below and SL6.10e's docs: compileall passed, and all 1803 tests
rebase_check.py verify after the restack	Lists as dropped the ten commits of the merged stack, which the tip holds under their merged SHAs (SL6.6c through SL6.8c), as --onto intends; this branch's three commits are kept and signed
Public names	Every Rust name in the guide and in the README's library part is in the tip's public-API snapshots, but for the modules that the text calls private (guest::{root, view, gpt}); the module table's 36 rows are all public modules or items
Anchors that this PR links in other documents (guest-agent-guidelines.md#ownership, #build-the-space, #the-hosts-mapping-table, ci.md#cratesio-releases, run.md#run-openvmm-directly), and those that other documents link here (#testing, #guest-binaries, #error-codes, #the-nvx-rs-cli, #artifact-root, #layout)	Present at the tip
Claims reviews	Before the restack, a code-review agent checked the guide and the rewritten README parts: its five findings and Copilot's one are folded (a VM outlives its program on Windows only with windows_breakaway when the program runs in a job; vm::stop returns the report's read apart from the exit; KeyIdentity digests the key's compatibility prefix; bytes_read counts reaped children on Linux; library callers classify errors by kind alone; the program sends the mapping table only when it holds a mapping). After the restack, two code-review agents rechecked every statement against the tip. The rewritten parts' four findings are folded: ReadyListener::receive takes a timeout, not a deadline; on Windows the endpoints are named pipes, not entries of the VM directory; a capture's kernel command line holds only the caller's platform tokens and maxcpus; StillRunning also follows a failed spawn. The kept sections' eight findings are folded, as the last item of the nvx-rs/README.md bullet above lists. Copilot's review of the restack found one more, folded: the guide labels each runtime file with that file's own SHA-256 digest, as a release's SHA256SUMS lists it, not with a digest of the checksum file

nvx-rs/README.md is not the crate's documentation (lib.rs doesn't include it), so no doc test or cargo doc output changes, and nothing here is guest-gated: no Linux host, build or microVM run.

[Copilot]

🟡 Changes recommended

The documented restore sequence omits skipping MAPS when no exports are configured, so following it unconditionally would fail an otherwise valid restore because encoding an empty mapping table returns an error.

1 open issue

• Skip MAPS encoding when no host mappings are configured · New

What changed in this PR

Updates the documentation for the final public nvx library, separating its microVM mechanisms from caller-owned state and policy and NVX’s private programs.

Changes:

• Adds one library guide covering cold boot, snapshot restore, and reattachment, linked to compiled examples.
• Slims the crate README to the final public API and clarifies caller responsibilities.
• Adds library-guide and guest-agent-guideline links to the repository landing page.

File	Description
README.md	Updates the crate description and links the library and guest-agent guides.
nvx-rs/​README.md	Documents the final public modules and separates private implementation details.
doc/​library.md	Introduces the three host workflows and caller-owned responsibilities.

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

The documentation targets several pending stacked branches rather than this snapshot, requiring maintainer verification of API and protocol claims against the integrated tree after the planned rebase.

No open issues 🎉

1 resolved since last review

• Skip MAPS encoding when no host mappings are configured

_{Review effort: Balanced}

[github-actions]

This pull request changes no existing test

Relocated unchanged: 0; added: 0. Compared the merge base ab2673e7751e with 9dc06ebaf8d3.

[Copilot]

🟡 Changes recommended

The documentation conflates an artifact’s digest with the checksum file’s digest, which can give different release artifacts the same identity and hide artifact changes from runtime-identity comparisons.

1 open issue

• Use each artifact's SHA-256 digest, not the checksum file's digest · New

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

No active review issues are reported for the documentation updates clarifying the public API and caller-owned responsibilities.

No open issues 🎉

1 resolved since last review

• Use each artifact's SHA-256 digest, not the checksum file's digest

_{Review effort: Balanced}

[Pedro Henrique Penna (ppenna)]

Reran the failed jobs of CI run 43345750757 once, as attempt 2, with gh run rerun 43345750757 --repo microsoft/nvx --failed.

Attempt 1 failed only nvx-rs / windows-latest, in exec_lock::exec_processes_contend_but_other_sandboxes_and_stop_proceed (tests/cli/exec_lock.rs:132). There, sandbox stop --timeout 0.1 failed with error[still-running]: cannot confirm exit of VM process 6580. This pull request changes only documentation. The same test failed the same way on feature/nvx-refactor at 12a90c4a0ee, in push run 43330747184. With --timeout 0.1, the stop has about 0.1 s to confirm the forced exit, and a loaded Windows runner can miss that. The flaky test will be fixed separately.