[Enrique Saurez (esaurez)]

A platform template's snapshot must hold no tenant's root, so that every clone that a restore starts attaches its own image, upper, and export. Today only the shell nvx-snapshot prepares a capture, after the layered init has assembled the root. This adds nvx::guest::clone, through which a privileged guest init or agent, whether or not it is PID 1, prepares its guest for a capture before its root's assembly, behind its own fence of workload admission, and requests the capture.

Part of #840: the first of its two pull requests. The second, #932, adds a template mode to the test adapter's guest, which uses this module; #841 and #842 build on it too.

Chain: #886 → this PR → #932 → #884 → #887 → #841 PR 3, on dev; #879, #881 and #885 have merged.

What changed

The preparation (nvx-rs/src/guest/clone.rs). CapturePreparation::new(fence, devices) takes the caller's AdmissionFence and the template's Devices: the distro and scratch block devices, which their MMIO windows name, and the host filesystem device's virtio-fs tag. CapturePreparation::prepare, in order:

1. closes the fence, so that no execution starts. Closing acquires the fence: AdmissionFence::close fails while the fence is closed, such as by another preparation through another handle of the same admission state, and a preparation opens only a fence that it closed;
2. reads at most MOUNT_TABLE_LIMIT (1 MiB) of /proc/self/mountinfo, and refuses, with a Mounted that names the first such mount, anything mounted from the distro device or one of its partitions, the scratch device, an overlay, or the filesystem tag, bind mounts included;
3. waits for the time ABI's boot checks, runs its capture checks, and suppresses the stall detectors, as nvx-time pre-capture does,

and returns an owned CaptureBarrier. A preparation that fails opens the fence again, and leaves the detectors' settings as they were.

The capture. CaptureBarrier::capture reads the VM generation ID and calls TimeAbi::capture with the platform tier's request, which keeps no scratch. It returns:

• Captured::Continued, once it opened the fence and restored the detectors' settings;
• or, in a clone, Captured::Restored, with the fence still closed and the detectors still suppressed. Restored::into_parts hands the Restore that repair (nvx-rs: repair a restored clone in the guest, with an owned seed and one acknowledgment #842) takes next, and the closed fence, to the caller, which opens the fence once repair acknowledged the restore. The time daemon restores the detectors' settings when the restore finishes.

CaptureBarrier::cancel, a dropped barrier, and a failure to read the VM generation ID open the fence, then restore the detectors' settings. A capture request that fails restores the settings but leaves the fence closed. Each failure is a CaptureError, which names the CaptureStage that failed and its CaptureCause.

The mount table (nvx-rs/src/guest/clone/mounts.rs). A strict parser of the kernel's mountinfo lines, with its escapes, refuses any line of another form. A mount on a block device is from the distro or the scratch device when the device's canonical sysfs entry, /sys/dev/block/MAJ:MIN, is below the device window's sysfs directory, which covers a GPT disk's partitions, those of the extended major included. A virtiofs mount whose source is the tag is from the host filesystem device, which covers a host export and its bind mounts, and any overlay mount blocks a capture. A table longer than the limit, a malformed line, or a mount on a block device that sysfs doesn't show fails the check; a window whose device the kernel hasn't added has nothing mounted from it.

The time ABI (nvx-rs/src/guest/time/):

• TimeAbi::pre_capture and TimeAbi::cancel_capture are crate-internal typed calls, through which nvx-time pre-capture and nvx-time cancel-capture now run, with unchanged diagnostics and statuses.
• Like the other typed calls, pre_capture fails when the thread may still hold some of the permission for the time ABI's ports. A preparation that fails but still holds the detectors' suppression says so, and its caller restores their settings: nvx-time pre-capture before it fails, so it no longer leaves them suppressed after a port-release failure, and the barrier before it reports the failure.
• The stall detectors' suppression now saves under the lock that its restore takes. A save that fails undoes only what it changed, so it never restores another capture's record, and keeps its record when it can't undo every change.

Supporting changes. nvx::guest::root shares its lookup of a virtio MMIO window's sysfs directories; root assembly finds its devices as before. The crate's README and documentation list the module.

Design notes

• Restored clones. The issue specifies that Captured::Restored keeps the detectors suppressed, and leaves the fence's state open. Guide 5.5.7 runs nothing before the restore's acknowledgement, and 5.5.8 thaws the workload only after it, so the fence stays closed, and the caller opens it after repair.
• Failed requests. TimeAbi::capture can fail after it found a restore packet, in a clone whose repair it couldn't complete, which the barrier can't tell from a source's failure. A failed request therefore leaves the fence closed, and only restores the detectors' settings; the caller ends the VM either way. A rejected or rolled-back capture is not a failure: it returns Captured::Continued, with both barriers released.
• Release order. The barrier opens the fence first, then restores the detectors' settings, as guide 5.3.2 orders it. A failure to restore them is a CaptureStage::Release error, after which the caller ends the VM, unless the thread may still hold port permission, which takes precedence.
• Entropy. A restore writes its entropy to /run/nvx/restore-entropy, as nvx-snapshot does today.

Validation

At 060eefc, the head, rebased onto #886 at 7c97c9c without conflicts or changes to its own lines, and with no VM: the module's tests use fakes for the mount table, the fence, and the time ABI, as the issue specifies, and temporary procfs, sysfs, and detector trees for the live lookups and the suppression.

Each of this PR's commits passes, on Linux x86_64, cargo fmt --check; cargo clippy with -D warnings with all features and targets, of the library with default and without features, and with the guest feature alone; the host modules' layering test; the macOS check; and the guest::{clone,time,root} tests; and on Windows x86_64, the same formatting, Clippy, and layering checks.

At the head, on Linux x86_64 (toolchain 1.95.0, MSRV 1.89), check-nvx-rs: cargo fmt --check; cargo clippy with --all-targets --all-features, --lib, --lib --no-default-features, and the guest feature alone, -D warnings; cargo test with all, default, and no features, 1,434 library tests passing with all features; the host modules' layering test; the guest::{clone,time,root} tests five more times; the bundled artifacts test; cargo doc with -D warnings; cargo +1.89 check; the macOS check; the guest binaries' lint, tests, build, and check; and the runtime adapter's protocol-only, host-only, and musl guest-only configurations, with their MSRV checks.

On Windows x86_64: nvx.py verify; check-nvx-rs's host steps, with 866 library tests passing with all features, and the layering test; and the runtime adapter's protocol-only and host-only configurations.

CI's pull-request run at the head, which started before this PR's base moved to #886's branch, passed. A run dispatched at #932's head, which holds this PR, passed every job but one, a runtime adapter network scenario on Linux with MSHV that neither PR changes; #932 describes it.
A final review of the change, and Copilot's review, found and fixed: a restored clone that opened its fence before repair, in the code and then in the module's example; a preparation that skipped the time ABI's port-release check; a suppression save that could restore another capture's record, or lose its own; cleanup errors that could hide a retained port permission, or, in a failed capture, be dropped; and a second preparation that could reopen a fence that another preparation's barrier held closed.

A final review of the rebase, and Copilot's review at the head, found no issues.

[Copilot]

🔵 Needs a closer look

The privileged capture lifecycle warrants human review, particularly its unresolved detector-restoration error handling.

1 open issue

• Propagate release failures during capture cleanup · New

What changed in this PR

Adds typed guest-side preparation for tenant-free platform snapshots before root assembly, establishing the capture API needed by the upcoming template adapter and clone-repair work.

Changes:

• Adds capture preparation, admission fencing, mount checks, and capture outcomes.
• Shares time-ABI preparation calls and strengthens detector-suppression rollback.
• Adds lifecycle and lookup tests, plus public API documentation.

File	Description
nvx-rs/​src/​lib.rs	Lists the new guest capture API.
nvx-rs/​src/​guest/​time/​system.rs	Serializes suppression saves and restores; adds rollback tests.
nvx-rs/​src/​guest/​time/​mod.rs	Exposes preparation errors internally.
nvx-rs/​src/​guest/​time/​commands.rs	Routes capture preparation commands through typed calls.
nvx-rs/​src/​guest/​time/​api.rs	Adds typed preparation, cancellation, and permission-error handling.
nvx-rs/​src/​guest/​root/​kernel.rs	Shares kernel interface paths internally.
nvx-rs/​src/​guest/​root/​block.rs	Extracts shared MMIO-window lookup.
nvx-rs/​src/​guest/​root.rs	Re-exports shared lookup helpers internally.
nvx-rs/​src/​guest/​mod.rs	Exposes the x86-64 clone module.
nvx-rs/​src/​guest/​clone/​tests.rs	Tests capture ordering, cleanup, outcomes, and device lookups.
nvx-rs/​src/​guest/​clone/​mounts.rs	Parses mount information and identifies capture-blocking mounts.
nvx-rs/​src/​guest/​clone.rs	Implements preparation, barriers, outcomes, and typed errors.
nvx-rs/​README.md	Documents the capture API and lifecycle.

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Privileged snapshot transitions, admission fencing, and detector-state recovery warrant final human review, with cross-backend VM validation deferred to follow-up work.

No open issues 🎉

1 previously missed issue

In code that hasn't changed since last review

Example opens fence before repair and restore acknowledgment

nvx-rs/​src/​guest/​clone.rs:81

The example opens admission immediately after into_parts(), but neither that method nor the default capture request completes repair or acknowledges the restore. Following this example would admit workloads before reseeding/repair and leave the detectors suppressed because restore_finish was never called. Please show an explicit repair-and-acknowledgment step before fence.open(), or stop the example with the fence closed until that step is available.

1 resolved since last review

• Propagate release failures during capture cleanup

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Overlapping preparations sharing admission state can reopen the workload fence while another capture barrier remains active.

1 open issue

• Prevent shared-gate preparation from reopening an active capture fence · New

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Snapshot isolation, restore-time admission fencing, and shared detector-state cleanup warrant final human review, with VM integration validation deferred to follow-up work.

No open issues 🎉

1 resolved since last review

• Prevent shared-gate preparation from reopening an active capture fence

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

The current fake-based tests need planned KVM/MSHV/WHP integration coverage to validate snapshot isolation’s reliance on live mountinfo/sysfs identities and admission-fence persistence across restore.

No open issues 🎉

1 resolved since last review

• Prevent shared-gate preparation from reopening an active capture fence

_{Review effort: Balanced}