[Pedro Henrique Penna (ppenna)]

Part of #1130 (SL6.10b, "The host and snapshot design separates the VMM, the library and its users"). Parent #1090, umbrella #1076.

Rebased onto feature/nvx-refactor 83c6231305e, where every code slice of #1076 and SL6.10c (design 4.*) have merged; only this PR's commit was replayed.

What and why

The host and lifecycle design still described an NVX launcher and a host control library that keep per-sandbox state, supervise VMMs and deliver the mapping table, snapshot tiers as lifecycle points with a sharing scope, template compatibility keys, and a managed sandbox lifecycle of the host. The slim nvx keeps no durable state and runs no supervisor: its callers own their stores, paths, outputs and locks. This PR does SL6.10b's Scope and no more. It edits the named pages in place, with one split of each responsibility between what OpenVMM provides, what nvx checks or drives, and what callers (an orchestrator, or NVX's CLI) and guest inits own:

• 1.3 names the callers, with NVX's CLI as one, which the crate builds with its cli feature outside its documented API, keeping its own store and the identity pins of its exports; the nvx library, which keeps no durable state, takes no lock but its internal Windows spawn lock, and starts no process but OpenVMM; the caller-owned VM and snapshot directories; and the guest's init and helpers with the nvx guest library, whose space is nvx-init's private reference code.
• 1.4 adds what nvx checks (private VM directories, the strict snapshot directory, verified processes and endpoint peers, the runtime identity) and what its caller keeps (1.4.6): stable, private paths and directories, and the objects at the paths of an ExportPlan, which names paths only, and of which NVX's CLI pins the objects in a workload's writable parts; its outputs, which nvx removes none of once a launch is created, while OpenVMM removes its own console sockets on Linux; per-snapshot locks on Linux, with why; and its own spawns on Windows. The capability's handling, and block identities, follow the code.
• 1.5 gives each contract of Table 1.1 its owner, adds nvx's boot contract, activation record, snapshot key and control protocol, replaces "Template Compatibility" with snapshot compatibility through the key, KeyIdentity and Snapshot::accepts, and adds persisted state and the runtime identity and its labels (1.5.4).
• 2.1, 3.4 and 3.5 describe configuration ownership, the one platform capture of nvx (a blockless boot with a placeholder image and a dormant scratch) and its complete restore-time inputs (a shorter image, an absent scratch, an aggregate on the dormant slot, a NIC template's own policy), and caller-owned identity and proxy.
• 5.1 separates OpenVMM's, nvx's and the caller's boot tokens; 5.2 defines Ready (5.2.4), the host's mapping table and the public MappingTable, whose mapper is the private space's (5.2.5), and the lifecycle operations of nvx, with NVX's CLI's sandbox as one caller (5.2.6).
• 5.3 and 5.4 describe tiers only as device configurations, the capture that nvx configures, who prepares the guest, finishing a capture (5.3.8), and the strict snapshot directory: the envelope of key.bin and snapshot.json around OpenVMM's openvmm/, its checks, and its hard-linked restore view.
• 5.5 adds who repairs a platform restore and the order of a restore's activation to Ready with its own network policy (5.5.9); 5.6 adds the repair and activation statuses of nvx::protocol::status, the ErrorKinds that callers act on, and RestoreError's attribution.

Kept accurate and in place. 5.5.5's restore packet is unchanged: the issue's "restore packet 6" is now version 1 of OpenVMM's v4 microVM (RESTORE_PACKET_VERSION = 1 in nvx-rs/src/contract.rs), whose NETWORK flag carries what version 6 added. The order of a restore with a new network policy stays in 3.5.6, now with the platform clone's order, which 5.5.9 details. The host-clock correction of the time samples stays in 5.5.7's step 3.

The final state, rechecked at 83c6231305e. ExportPlan holds paths only, the caller keeps them stable, and the CLI's crate-private PlannedExport holds the pins (SL6.5b). host::sandbox and host::network::policy are crate-private (SL6.7b). Callers act on ErrorKind, and ErrorCode is private (SL6.8c). The guest's space and mapper are private, and only MappingTable and the mapping values stay public (SL6.13b). NVXC v2 is the only control protocol, internal, and its Ready carries the protocol version, which NVX's host checks (SL4.4a to SL4.4d). The rebase needed no conflict resolution; the recheck at the tip changed three passages: 1.3 no longer calls the CLI crate-private (host::cli is a hidden public module behind the cli feature), 1.4.6 names the ExportPlan/CLI-pins split, and 1.4.6 notes that OpenVMM removes its control and boot-console sockets at teardown on Linux. 5.2.2's order, the restore-ready event before the vCPUs' release and the guest's repair, was checked against OpenVMM's code at the pin (openvmm_core/src/worker/dispatch/restore.rs) and stays; OpenVMM's Guide, which says otherwise, is a follow-up outside #1076.

OpenVMM claims corrected on the way. Checking each claim against the code also corrected pages that described OpenVMM's paired tiers out of date: a bound block's identity is the SHA-256 digest of its file by default, and a storage generation only when its owner opts in (openvmm/openvmm/openvmm_entry/src/cli_args/microvm.rs); a platform restore may attach a shorter image, declare its scratch absent, and bind a new aggregate to the dormant slot.

Not in this PR, per #1130: new design documents or other design pages (design 4.* is SL6.10c's, #1550; the library guide SL6.10a's; the CLI, build, CI and migration documents later slices'), new tiers, formats, packet fields or behavior, tier types, and removed stores or supervisors as library services.

Size. 0 core lines and 0 counted files (estimate 0): documentation only. BOOT_CONTRACT_VERSION, CONTROL_CONTRACT_REVISION and the public API are unchanged.

Validation

The orchestration checkout's local_gates.py --files over the twelve pages selects test-changes, markdown-links, test-layout and nvx-cli, run here at d3466ae41d6 (on 83c6231305e) from this branch's own definitions:

Check	Result
python scripts/check_markdown_links.py	Passed (Windows)
python scripts/check_test_layout.py	Passed (Windows)
python scripts/check_test_changes.py --base origin/feature/nvx-refactor	0 changes to existing tests
validate-nvx's Windows steps: python -m compileall -q scripts, its python -m unittest modules, python scripts\test_adversarial.py, .github\skills\nvx-host-connect\scripts\test_hosts.py, and nvx.py help	Passed: 1803 tests OK (73 skipped); test_hosts.py 4 OK; every help command exits 0. test_adversarial.py's first run, on a host shared with other agents' runs, reported one error that its output did not keep; four reruns passed, 84 tests OK (11 skipped) each
The case matrix's check (check_matrix.py, SL5.2)	Passed
A code-review subagent checked every added or changed claim against nvx-rs/src, openvmm/, guest/common and doc/guest-agent-guidelines.md	At the stack base: six findings, all fixed (validation order in vm::create, output cleanup and a missing report, KeyIdentity's exclusions, the report-only restore finish's processes, the capture request's deadline, and the CLI's pass-through of nvx_workload_account=create). At the final tip: two findings, both fixed (the CLI's module is hidden, not crate-private; OpenVMM removes its console sockets at teardown)

No code, runtime behavior or test changes, so no build, host or microVM scenario ran. Left to CI: the documentation-only run that its change classification selects.

[Copilot]

🔵 Needs a closer look

The missing OpenVMM submodule prevents verification of the SHA-256 block identity, shorter-image, absent-scratch, and dormant-slot aggregate restore claims against the pinned implementation.

No open issues 🎉

What changed in this PR

Updates the host and lifecycle design for the slim nvx library under #1130, separating OpenVMM’s responsibilities from library mechanisms and caller-owned policy and state. The PR changes documentation only, with no runtime or API changes.

Changes:

• Clarifies ownership of configuration, paths, outputs, locks, runtime identities, and guest behavior.
• Documents snapshot compatibility, strict directory layout, capture completion, and restore-time attachments.
• Defines boot-token ownership, Ready, mapping-table delivery, restore activation, and failure handling.

File	Description
doc/​design/​5.6-shutdown-and-failure-semantics.md	Documents exit evidence, repair statuses, and caller-facing errors.
doc/​design/​5.5-restore-protocol.md	Details platform repair and activation through Ready.
doc/​design/​5.4-snapshot-artifact-and-attachment-model.md	Defines the strict snapshot envelope, validation, tiers, and attachments.
doc/​design/​5.3-snapshot-protocol.md	Clarifies capture configuration, barriers, deadlines, and completion.
doc/​design/​5.2-readiness-and-runtime-control.md	Separates Ready, mapping delivery, library operations, and CLI lifecycle.
doc/​design/​5.1-boot-protocol.md	Distinguishes OpenVMM, library, and caller boot tokens.
doc/​design/​3.5-network.md	Explains caller-selected networking and restore-specific policy activation.
doc/​design/​3.4-block-storage.md	Clarifies block identities and platform image/scratch rules.
doc/​design/​2.1-machine-model-and-configuration.md	Assigns configuration ownership and describes restore-time inputs.
doc/​design/​1.5-compatibility-and-versioning-model.md	Defines contract owners, snapshot keys, and runtime identity.
doc/​design/​1.4-trust-boundaries.md	Documents library checks and caller path, output, and lock obligations.
doc/​design/​1.3-system-components-and-responsibilities.md	Separates callers, library, VMM, and guest responsibilities.

_{Review effort: Balanced}

[Pedro Henrique Penna (ppenna)]

No change needed for Copilot's review note on the OpenVMM claims, which it could not check because the review had no OpenVMM submodule. Each one holds at the pinned OpenVMM, 14dc4116ec7 (this branch's openvmm gitlink):

• A bound block's identity is SHA-256 by default, and a storage generation only when its owner opts in. Restore reads and hashes a SHA-256 block, but doesn't read a generation block: openvmm/openvmm_entry/src/cli_args/microvm.rs lines 329 and 865, and openvmm/openvmm_helpers/src/snapshot/restore.rs lines 279 to 282.
• A platform restore may attach a shorter image with the captured block sizes, and reads past its end return zeros: Guide/src/user_guide/openvmm/snapshots.md lines 190 to 195.
• A platform restore may declare its fresh scratch absent with --restore-absent-scratch: cli_args/microvm.rs lines 285 to 291, and snapshots.md lines 195 to 202.
• A platform snapshot may bind a new --mount-aggregate to its dormant filesystem slot: snapshots.md lines 500 to 503.

[github-actions]

This pull request changes no existing test

Relocated unchanged: 0; added: 0. Compared the merge base 83c6231305ef with d3466ae41d6d.

[Copilot]

🔵 Needs a closer look

The snapshot lacks OpenVMM source, preventing independent verification of block digest checks, absent-scratch behavior, and restore-ready ordering against the pinned implementation.

No open issues 🎉

_{Review effort: Balanced}

[Pedro Henrique Penna (ppenna)]

No change needed for this review's note either: 5.2.2's restore-ready order holds at the pinned OpenVMM, 14dc4116ec7. LoadedVm::start_state_units in openvmm/openvmm_core/src/worker/dispatch/restore.rs (lines 312 to 362) gates input, starts the state units, writes and flushes the readiness event, arms the gate's deadline, and only then drops the guard that holds the restored vCPUs (start_guard.take()), so the event precedes the guest's repair and its acknowledgement. The block digest and absent-scratch claims are covered, with file and line references, in the earlier comment: #1553 (comment).