nvx-rs: make the rustdoc and module diagrams describe the final public API (SL6.10g)

doc/acceptance-case-matrix.md

@@ -478,15 +478,15 @@ this matrix. The README's own code is no doctest.
 | `nvx-rs/src/activation/mod.rs - activation (line 130)` | kept |  |
 | `nvx-rs/src/exec/mod.rs - exec (line 113)` | retired | The exec engine leaves (SL6.11a) |
 | `nvx-rs/src/gpt/mod.rs - gpt (line 43)` | kept |  |
-| `nvx-rs/src/guest/activation.rs - guest::activation (line 151)` | kept | SL6.11c rewrote it on `guest::snapshot::capture`, when its capture preparation and admission fence left (#1087) |
+| `nvx-rs/src/guest/activation.rs - guest::activation (line 127)` | kept | SL6.11c rewrote it on `guest::snapshot::capture`, when its capture preparation and admission fence left (#1087) |
 | `nvx-rs/src/guest/activation/state.rs - guest::activation::state::Activation (line 54)` | kept | SL6.13b (#1127) rewrote it without the guest's space, which became private: its agent applies the record in its own space |
 | `nvx-rs/src/guest/cgroup.rs - guest::cgroup (line 36)` | retired | `guest::cgroup` leaves (SL6.11b) |
 | `nvx-rs/src/guest/entry.rs - guest::entry (line 90)` | retired | `guest::entry` leaves (SL6.11b) |
 | `nvx-rs/src/guest/exec.rs - guest::exec (line 79)` | retired | `guest::exec` leaves (SL6.11b) |
 | `nvx-rs/src/guest/exec.rs - guest::exec::Execution::adopt (line 619)` | retired | `guest::exec` leaves (SL6.11b) |
 | `nvx-rs/src/guest/gpt.rs - guest::gpt (line 18)` | kept | SL6.13b (#1127) moved it to the module's unit tests, `nvx-rs/src/guest/gpt/tests.rs::a_disk_s_steps_compile`, since the guest's space became private |
 | `nvx-rs/src/guest/mappings/mapper.rs - guest::mappings::mapper (line 107)` | kept | SL6.11d (#1123) moved it to the mapper's unit tests, `nvx-rs/src/guest/mappings/mapper/tests.rs::a_mapper_s_steps_compile`, which map and unmount through the seams that NVX's programs use, since the mapper's `apply` and `teardown`, which only tests used, left |
-| `nvx-rs/src/guest/mappings/table.rs - guest::mappings::table::MappingTable (line 47)` | kept |  |
+| `nvx-rs/src/guest/mappings/table.rs - guest::mappings::table::MappingTable (line 46)` | kept |  |
 | `nvx-rs/src/guest/mod.rs - guest (line 33)` | kept | The guest-agent guidelines quote it |
 | `nvx-rs/src/guest/nvxs.rs - guest::nvxs (line 22)` | kept |  |
 | `nvx-rs/src/guest/process.rs - guest::process (line 12)` | retired | `guest::process` leaves (SL6.11b) |
@@ -497,17 +497,17 @@ this matrix. The README's own code is no doctest.
 | `nvx-rs/src/guest/spawn.rs - guest::spawn (line 41)` | retired | `guest::spawn` leaves (SL6.11b) |
 | `nvx-rs/src/guest/spawn.rs - guest::spawn::LaunchStage::from_code (line 201)` | retired | `LaunchStage::from_code` and its test, `launch_stages_keep_their_numbers`, leave with `guest::spawn` (SL6.11b). The stages of nvx-init's executions keep their numbers in the crate's own fork boundary, whose launch report `nvx-rs/src/guest/init/tests/exec.rs::native_workload_cwd_accepts_procfs_links_but_closes_inherited_descriptors` reads from a real launch |
 | `nvx-rs/src/guest/terminal.rs - guest::terminal (line 10)` | kept |  |
-| `nvx-rs/src/guest/time/mod.rs - guest::time (line 9)` | kept | SL6.11c removed its capture and restore finish, which became crate-private: `guest::snapshot::capture` runs them |
+| `nvx-rs/src/guest/time/mod.rs - guest::time (line 10)` | kept | SL6.11c removed its capture and restore finish, which became crate-private: `guest::snapshot::capture` runs them |
 | `nvx-rs/src/host/sandbox/prepared.rs - host::sandbox::prepared::PreparedLaunch (line 92)` | retired | `PreparedLaunch` leaves with the checked-file handoff (SL6.3, #1122) |
 | `nvx-rs/src/host/store/mod.rs - host::store (line 72)` | retired | The sandbox store leaves (SL6.1, #1121) |
 | `nvx-rs/src/host/supervisor/mod.rs - host::supervisor (line 32)` | retired | The store-coupled supervisor leaves with the sandbox store (SL6.1, #1121), and `host::supervisor`, the transitional public path of the low-level spawn, with SL6.3 (#1122): `host::vm` spawns VMMs, and the tests of the spawn moved to `nvx-rs/src/host/spawn/tests.rs` and `nvx-rs/src/host/process/tests/orchestrator.rs` |
 | `nvx-rs/src/host/template/clone.rs - host::template::clone::ClonePlan (line 247)` | retired | `ClonePlan` and `CloneRequest` leave with the old clone path (SL6.2b, #1121) |
 | `nvx-rs/src/host/template/plan.rs - host::template::plan::TemplatePlan (line 137)` | retired | `TemplatePlan` leaves with the template store (SL6.2a, #1121) |
 | `nvx-rs/src/host/template/store.rs - host::template::store::Store (line 473)` | retired | The template store leaves (SL6.2a, #1121) |
 | `nvx-rs/src/host/transport.rs - host::transport (line 22)` | kept |  |
-| `nvx-rs/src/lib.rs - (line 58)` | rewritten | Its `Instance` and sandbox store leave (SL6.1, #1121): `nvx-rs/src/lib.rs - (line 53)` compiles a cold boot and a stop through `host::vm` |
+| `nvx-rs/src/lib.rs - (line 58)` | rewritten | Its `Instance` and sandbox store leave (SL6.1, #1121): `nvx-rs/src/lib.rs - (line 67)` compiles a cold boot and a stop through `host::vm` |
 | `nvx-rs/src/protocol/nvxs/mod.rs - protocol::nvxs (line 68)` | kept |  |
 | `nvx-rs/src/host/snapshot/capture.rs - host::snapshot::capture::finish_capture (line 48)` | kept |  |
 | `nvx-rs/src/host/store/mod.rs - host::store (line 104)` | retired | The sandbox store leaves (SL6.1, #1121) |
-| `nvx-rs/README.md`, its Example: an instance through `LaunchSpec` and the sandbox store | rewritten | Nothing compiles it. `nvx-rs/examples/host-workflows.rs` compiles the documented host workflows, and the library's guide (SL6.10a) replaces the example. SL6.1 (#1121) made it the cold boot that `nvx-rs/src/lib.rs - (line 53)` compiles |
+| `nvx-rs/README.md`, its Example: an instance through `LaunchSpec` and the sandbox store | rewritten | Nothing compiles it. `nvx-rs/examples/host-workflows.rs` compiles the documented host workflows, and the library's guide (SL6.10a) replaces the example. SL6.1 (#1121) made it the cold boot that `nvx-rs/src/lib.rs - (line 67)` compiles |
 | `nvx-rs/examples/external-launch.rs` | kept | Compiled with the crate's targets, and run by hand on a host. Since SL6.3 (#1122), which deletes `host::supervisor`, a minimal launcher of its own on `std::process` starts its VMM |

doc/ci.md

@@ -2432,21 +2432,24 @@ library's `gpt::crc::` tests, in two jobs.
 
 ## Module diagrams
 
-[`doc/modules`](modules/README.md) publishes diagrams of the modules of the
-[`nvx` crate](../nvx-rs/README.md): its top-level modules, the dependencies
+[`doc/modules`](modules/README.md) publishes diagrams of the public modules of
+the [`nvx` crate](../nvx-rs/README.md): its top-level modules, the dependencies
 between them, and the modules that each contains, on Linux and Windows.
 [`module_diagrams.py`](../scripts/module_diagrams.py) draws them. It exports
 the modules of the crate's library, with its `cli`, `testing`, and `guest`
 features, for each platform's target with
-[cargo-modules](https://github.com/regexident/cargo-modules), merges the
-platforms' modules, lays out the diagrams with Graphviz, and writes them with
-the page that shows them. Unless it analyzes with `cfg(test)`, cargo-modules
-drops as a test module every module whose cfg holds when `test` holds and every
-other condition fails, such as one under `cfg(not(windows))`, so the script
-also reads its analysis with `cfg(test)` and restores those modules, with their
-own uses in place of those that the plain analysis moves to the modules that
-contain them, and stops at a cfg that depends on `test` in another way. Nobody
-edits the diagrams by hand:
+[cargo-modules](https://github.com/regexident/cargo-modules), keeps those of
+each platform's public API, without the modules of NVX's own programs, which
+the crate hides and the script lists, merges the platforms' modules, lays out
+the diagrams with Graphviz, and writes them with the page that shows them.
+Unless it analyzes with `cfg(test)`, cargo-modules drops as a test module every
+module whose cfg holds when `test` holds and every other condition fails, such
+as one under `cfg(not(windows))`, so the script also reads its analysis with
+`cfg(test)` and restores those modules, with their own uses in place of those
+that the plain analysis moves to the modules that contain them, and stops at a
+cfg that depends on `test` in another way, but for `any(test, feature = "cli")`
+and its like, whose feature the script enables. Nobody edits the diagrams by
+hand:
 [`module-diagrams.yml`](../.github/workflows/module-diagrams.yml) draws them
 again every night, with the nightly full run of CI, and commits them to `dev`
 when they changed, so that `dev` takes at most one push of them a night outside

doc/modules/README.md

@@ -2,22 +2,23 @@
 
 # Module diagrams
 
-The modules of the [`nvx` crate](../../nvx-rs/README.md), the modules that each
-contains, and the dependencies between them, as
+The public modules of the [`nvx` crate](../../nvx-rs/README.md), the modules
+that each contains, and the dependencies between them, as
 [cargo-modules](https://github.com/regexident/cargo-modules) 0.27.0 finds them
-and Graphviz 2.43.0 draws them. They cover the crate's library with its `cli`,
-`testing`, and `guest` features, on Linux (`x86_64-unknown-linux-musl`) and
-Windows (`x86_64-pc-windows-msvc`). CI draws them again after every merge to
-`dev` that changes the crate, and commits them when they change; see [Module
+and Graphviz 2.43.0 draws them. They cover the crate's public API, as its
+library builds with its `cli`, `testing`, and `guest` features, on Linux
+(`x86_64-unknown-linux-musl`) and Windows (`x86_64-pc-windows-msvc`): each
+module that is public, as are the modules that contain it, but the modules of
+NVX's own programs, which the crate hides. CI draws them again every night, and
+commits them to `dev` when they change; see [Module
 diagrams](../ci.md#module-diagrams).
 
-Each box is a module, colored by the part of the crate that holds it: blue for
-the modules that the host and the guest share, purple for the host, teal for
-the guest, and amber for the test doubles. A solid box is a public module, and
-a dashed box a private one, unless it names another visibility, such as
-`pub(crate)`. A box that names platforms, as in *Linux only*, is a module that
-only they build, as are the modules that it contains. The diagrams leave out
-the crate's tests and binaries, and other crates.
+Each box is a public module, colored by the part of the crate that holds it:
+blue for the modules that the host and the guest share, purple for the host,
+and teal for the guest. A box that names platforms, as in *Linux only*, is a
+module that only they build, as are the modules that it contains. The diagrams
+leave out the crate's private modules, its tests and binaries, and other
+crates.
 
 ## Overview
 
@@ -34,7 +35,8 @@ uses the second, as cargo-modules finds them: a module uses another whose items
 it imports, re-exports included, or whose items the definitions of its own
 items name, which counts the implementations of a type's traits toward the
 type's module, wherever they are. The crate's own arrows are its re-exports.
-The uses within a top-level module are left out.
+The uses within a top-level module, and those of the modules that the diagrams
+leave out, are left out.
 
 ![Dependencies](dependencies.svg)
 
@@ -43,32 +45,17 @@ The uses within a top-level module are left out.
 The modules that each top-level module contains. An arrow points from a module
 to a module that it contains.
 
-### `nvx::activation`
-
-`nvx::activation`, in
-[`nvx-rs/src/activation/mod.rs`](../../nvx-rs/src/activation/mod.rs), contains
-2 modules.
-
-![The modules that nvx::activation contains](nvx-activation.svg)
-
-### `nvx::gpt`
-
-`nvx::gpt`, in [`nvx-rs/src/gpt/mod.rs`](../../nvx-rs/src/gpt/mod.rs), contains
-5 modules.
-
-![The modules that nvx::gpt contains](nvx-gpt.svg)
-
 ### `nvx::guest`
 
 `nvx::guest`, in [`nvx-rs/src/guest/mod.rs`](../../nvx-rs/src/guest/mod.rs),
-contains 97 modules.
+contains 7 modules.
 
 ![The modules that nvx::guest contains](nvx-guest.svg)
 
 ### `nvx::host`
 
 `nvx::host`, in [`nvx-rs/src/host/mod.rs`](../../nvx-rs/src/host/mod.rs),
-contains 135 modules.
+contains 11 modules.
 
 ![The modules that nvx::host contains](nvx-host.svg)
 
@@ -82,15 +69,7 @@ contains 135 modules.
 ### `nvx::protocol`
 
 `nvx::protocol`, in
-[`nvx-rs/src/protocol/mod.rs`](../../nvx-rs/src/protocol/mod.rs), contains 15
+[`nvx-rs/src/protocol/mod.rs`](../../nvx-rs/src/protocol/mod.rs), contains 9
 modules.
 
 ![The modules that nvx::protocol contains](nvx-protocol.svg)
-
-### `nvx::testing`
-
-`nvx::testing`, in
-[`nvx-rs/src/testing/mod.rs`](../../nvx-rs/src/testing/mod.rs), contains 1
-module.
-
-![The modules that nvx::testing contains](nvx-testing.svg)