[Pedro Henrique Penna (ppenna)]

Part of #1130 (SL7.9, "Init agents have guidelines"). Parent #1090, umbrella #1076.

What and why

Authors of init agents had no single contract for building a guest's space, running executions, coordinating a capture and completing a restore: design 4.2 and 4.3 mixed that procedure with the architecture, and described execution machinery that nvx-init doesn't use. This PR does SL7.9's Scope and no more:

• doc/guest-agent-guidelines.md (new) opens with the split: nvx parses the contracts, captures the guest and drives a restore's activation, but builds no space, runs no executions and enforces none of these obligations; the one exception is the time daemon, which TimeAbi::start_daemon forks. With nvx-init as the worked example, it covers:
  • ownership;
  • the space, labelled as NVX's internal reference code that nvx-init implements, not public API: its public inputs, and the rules of the root, the runtime file systems, the view, the mappings, the helpers and the one switch;
  • MappingTable's contract: parts in order, a latch after a failure, a complete table before any workload;
  • the executions: each child resets its priority, sets its credentials, changes to its working directory and execs, in its own process group, which end, cancellation, timeout and reset kill; priority, not limits (no cgroups and no per-execution limits; the RAM upper's cap is the one limit);
  • for an init with concurrent executions, the workspace contract (freeze(deadline), undone, ordered all-or-nothing freezes thawed in reverse, after_restore()), and what nvx-init does instead: it refuses a capture while an execution runs, or kills the process groups and sweeps;
  • the silent transport, the restore order (Activation::new, the space with the restore's own network policy, DNS and announcer, after_restore, complete, thaw, Ready), failures (Resumed, MustEnd) and replay.
• Compiled snippets. The general snippets are public-API doc tests, which the guidelines quote verbatim: the mapping-table excerpt in guest's rustdoc and the capture-outcome excerpt in guest::snapshot's. The space-interface snippets are the body of the private space's unit test, guest::init::boot::tests::the_reference_space_steps_compile, also quoted verbatim. No new harness.
• Rustdoc links. guest, guest::snapshot, guest::activation and activation link the guidelines.
• Design 4.2 and 4.3 keep only the architecture and boundaries, of nvx-init and of the older layered sandbox root and blockless managed root, which still run.
• doc/project-structure.md lists the page, as it lists every document in doc/. In nvx-rs: build every feature set, compile the documented examples, and give every old test a fate (SL5.1a) #1488's case matrix, the two new doc tests get a row, and the two doc tests whose lines the rustdoc links move keep theirs, at the new lines.

Not in this PR, per #1130: other guideline documents, a workspace trait or enforcement code in nvx, publishing the space module, cgroups, namespaces, per-execution roots or limits, a new example harness, or rewriting 4.2 and 4.3 beyond architecture and boundaries.

Commits. The first four are Enrique Saurez (@esaurez)'s first implementation (esaurez/slim-5.2.1-sl7.9-private-20261108), replayed with their authorship. The fifth checks each statement against nvx-init on feature/nvx-refactor and corrects those that didn't hold; its message lists them.

Rebase. Rebased from 5947e4e8 onto SL5.1a, which has merged (#1488), and now on feature/nvx-refactor 584c2ddd, after #1494. Both branches compiled the space's steps in a test of their own, in different files, so Git reported no conflict but one test would duplicate the other. This branch's version now lives in SL5.1a's test, under its name and in its file, which nvx-rs/README.md names (see below). Every statement was checked again at the new base, where the guest code is unchanged since 5947e4e8. Three statements no longer held, and are corrected: the host sends no MAPS for an empty mapping table, which no nvx_maps token announces; since #1490, no launch of NVX's CLI carries OpenVMM's older lifecycle token, which design 4.2 said the older CLI launches carry; and since #1494, no call of nvx starts the announcer, so the guidelines no longer name Announcer::start, and say that nvx-init forks the restored announcer and runs /sbin/nvx-ingress itself, while nvx-ingress start runs it for an agent that cannot hold it.

Size. 0 core lines and 0 counted files (estimate 0): documents, rustdoc comments and one unit test. BOOT_CONTRACT_VERSION, CONTROL_CONTRACT_REVISION and the public API are unchanged.

Validation

Check	Result
python scripts/check_markdown_links.py, python scripts/check_test_layout.py	Passed (Windows)
cargo fmt --all --check	Passed (Windows)
Clippy -D warnings: --all-targets --all-features, --lib, --lib --no-default-features, --lib --no-default-features --features serde, --lib --bins --features cli, --lib --bins --no-default-features --features testing	Passed (Windows). --all-targets --all-features also passed on Linux (nvx-kvm-test), where it compiles #1488's host-workflows and guest-workflows examples
Guest-only Clippy, --target x86_64-unknown-linux-musl --no-default-features --features guest --all-targets -- -D warnings (the Clippy run of nvx.py check-guest-binaries)	Passed (Linux); it compiles guest-workflows with guest alone
cargo doc --no-deps --all-features, RUSTDOCFLAGS=-D warnings	Passed on Windows and on Linux, where the guest modules' rustdoc builds
cargo test --doc --all-features	Linux: 34 passed, among them src/guest/mod.rs - guest (line 41), src/guest/snapshot.rs - guest::snapshot (line 25), src/guest/activation.rs - guest::activation (line 195) and src/activation/mod.rs - activation (line 130), the names that the matrix gives them. Windows: the activation doc test passed
guest::init::boot::tests::the_reference_space_steps_compile	Passed on Linux, with all features and with guest alone (musl). All of guest::init::boot::tests (musl): 14 passed, 2 ignored (they need a microVM)
cargo test --all-features --test security_checklist (#1488)	Linux: 10 passed, 1 ignored (the idle stand-in for a VM's process)
Quoted excerpts	Each of the guidelines' four rust blocks is identical to the code that it quotes
check_test_changes.py --base origin/feature/nvx-refactor	1 change, explained below

The table's results are from 0258d484, before the rebases onto 3c3dfce1 and 584c2ddd, which changed no content of these commits but the design 4.2 sentence and the announcer statements above. At 137d8029, Markdown links, test layout, fmt, rustdoc with warnings denied and the doc tests (Windows and Linux), and the private-space test (Linux, all features and guest alone), passed again, with the same doc-test names.

No runtime behavior changes, so no microVM scenario ran. Left to CI: the rest of check-nvx-rs (the full test suites, MSRV, macOS, public API, bundling) and the runtime adapter's checks.

Changes to existing tests (tests-modified)

• guest::init::boot::tests::the_reference_space_steps_compile (nvx-rs: build every feature set, compile the documented examples, and give every old test a fate (SL5.1a) #1488's) now holds the space's steps exactly as the guidelines quote them. It has two closures: a cold boot in the order of boot::cold_boot, and a restore in the order of boot::Restored::apply. Each has its own use lines and returns Box<dyn Error>, so that the quoted excerpt is self-contained, and comments mark where the init starts its helpers and its announcer. It drops nvx-rs: build every feature set, compile the documented examples, and give every old test a fate (SL5.1a) #1488's mapping-table closure and announcer callback: the guidelines quote the table's public half from guest's doc test instead. It still compiles its closures and runs none of them. This branch first had the same steps in a test of its own, guest::init::tests::documented_private_space_steps_compile. On the rebase, they moved into nvx-rs: build every feature set, compile the documented examples, and give every old test a fate (SL5.1a) #1488's test, so that one test compiles them.

Every other test of the area is kept. The doc tests of activation and guest::activation are unchanged, at lines 130 and 195 (were 123 and 189).

[github-actions]

This pull request changes existing tests

It modifies or removes 1 existing test asset(s), listed below. Review each with care: a change to a test can hide a regression that the test caught. See doc/contribute.md#changes-to-existing-tests.

Test code

Change	What	Before	After
modified test	fn the_reference_space_steps_compile in guest::init::boot::tests	nvx-rs/src/guest/init/boot/tests.rs:16	nvx-rs/src/guest/init/boot/tests.rs:15

Relocated unchanged: 0; added: 0. Compared the merge base 584c2ddde556 with 137d80296f24.

[Copilot]

🟢 Approval recommended

No active review issues require resolution.

No open issues 🎉

What changed in this PR

Implements SL7.9 of #1130 by documenting init-agent responsibilities separately from nvx’s library mechanisms, using nvx-init as the reference. Changes are limited to documentation, rustdoc examples and a compile-only unit test; runtime behavior and the public API are unchanged.

Changes:

• Adds guidelines for guest-space assembly, execution ownership, capture coordination, restore ordering and failure handling.
• Connects the guidelines to compiled examples through public-API doctests and the existing private-space unit test.
• Updates the architecture pages, documentation index and acceptance-case matrix.

File	Description
nvx-rs/​src/​guest/​snapshot.rs	Adds a capture-outcome doctest and guidelines link.
nvx-rs/​src/​guest/​mod.rs	Adds a mapping-table doctest and guidelines link.
nvx-rs/​src/​guest/​init/​boot/​tests.rs	Aligns compile-only space examples with the quoted guidelines.
nvx-rs/​src/​guest/​activation.rs	Links restore sequencing and caller obligations to the guidelines.
nvx-rs/​src/​activation/​mod.rs	Summarizes restore-space ordering and links the guidelines.
doc/​project-structure.md	Lists the new guidelines page.
doc/​guest-agent-guidelines.md	Defines init-agent responsibilities with nvx-init examples.
doc/​design/​4.3-isolation-and-resource-model.md	Distinguishes nvx-init’s VM-wide boundaries from legacy isolation.
doc/​design/​4.2-guest-agents-and-workload-model.md	Updates lifecycle ownership and the guest architecture diagram.
doc/​acceptance-case-matrix.md	Records the new doctests and updates existing doctest locations.

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

No active review issues are recorded for the documentation changes clarifying init-agent responsibilities and library boundaries.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

No active review issues are recorded for the documentation and example updates clarifying init-agent responsibilities and library–caller boundaries.

No open issues 🎉

_{Review effort: Balanced}