nvx-rs slimming 3.2.2: the CLI captures and restores named snapshots #1114

Parent: #1084, in #1076. Needs: #1102, #1108, #1109, #1110, #1113, #1117. Unblocks: #1112, #1118, #1131.

Goal. the CLI keeps named snapshots (#853), with one exclusive lock per snapshot for concurrent restores. snapshot capture creates one through host::vm::create with boot.capture, NVXC's capture request, Process::wait and snapshot::finish_capture, which takes the Exited proof and writes the snapshot's entries in the VM directory; the command then moves only key.bin, snapshot.json and openvmm/ into the named snapshot's private directory, and keeps them immutable; snapshot restore starts a sandbox from one, under the lock, through the private restore driver; and run --restore-snapshot restores a one-off VM from a strict snapshot.

Notes.

• run --restore-snapshot changes meaning. Today it passes a raw OpenVMM snapshot to OpenVMM; now it takes the CLI's strict snapshots, and refuses a raw one until NVX can snapshot blockless VMs.
• An interrupted capture isn't resumed. The capture VM goes through the store's launch journal, so the next command's recovery ends its VM and removes its directory, and the user captures again.
• A capture that doesn't end in time is never finished. If the VMM hasn't exited by the wait's deadline, the command stops the VM.
• One lock per snapshot. A restore holds its snapshot's exclusive lock from create, which adds the hard links, through the peer-verified restore-ready event or the VM's verified exit; deprovision holds it while it removes a restored sandbox's view, which the sandbox's record names. A restore whose command dies can't complete: OpenVMM checks the snapshot's files before it connects the restore-ready endpoint, once, so the CLI keeps no durable record of its restores, and the next command's recovery ends the VM like an interrupted launch.
• A named snapshot is captured before a layered root exists. The capture VM is blockless: its command line holds nvx_sandbox=1, so the shell /init hands it to nvx-init, which assembles no root and waits for NVXC's capture request. A restored VM gets its image, upper and workload setup at activation; no snapshot holds a running layered workload.

PRs, in order. Each PR has one goal, leaves dev green, and names in its description each old test of its area as kept, rewritten or retired, with each change that check_test_changes.py reports. Its tests follow the repository's test layout: a module's unit tests, and the code that only they use, sit in its tests.rs or tests/ and move with it. The estimates count core lines (code, not comments, docs or tests) and counted files; each PR records its measured values. Each PR does what its Scope says and no more: a case, input or layout that its Scope doesn't name, and whatever "Not in this PR" lists, is out of scope. Address every review comment within the scope, and ask before acting on one that asks for more. A PR whose measured core lines pass the stop that its Estimate names (twice the estimate, at most 600) stops and asks before continuing.

1. SL3.7a: The CLI keeps named snapshots.

   • Objective: The CLI needs a small persistent home for snapshots that users identify by name and can restore concurrently without changing a snapshot's files. This PR adds only the named snapshot directory and its per-snapshot exclusion.
   • Contents: The snapshot store (nvx-rs: template and clone commands in nvx-rs sandbox #853): named snapshots, each a private directory that holds exactly a snapshot's three entries, immutable and published whole by a rename, and one exclusive lock per snapshot, kept outside its directory. There is no index of restored VMs: each restored sandbox's record names its snapshot.
   • Scope:
     • The private host::cli::snapshots store and the sandbox record field that names a restored sandbox's snapshot.
     • One private directory per named snapshot, containing exactly key.bin, snapshot.json and openvmm/.
     • Whole publication by rename, immutable published entries, and one exclusive lock per snapshot stored outside that snapshot's directory.
     • Snapshot-name and layout tests for the store's supported named snapshots.
   • Not in this PR:
     • Durable in-flight capture or restore records, or reconciliation after restart: the launch journal handles interrupted VMs and a capture is redone.
     • An index from snapshots to restored VMs: each restored sandbox record names its own snapshot.
     • Shared lock modes or lock upgrades: the CLI starts one restore per command and needs one exclusive lock.
     • snapshot list, snapshot remove, retention policy or garbage collection: no command in this workstream needs them.
     • Snapshot capture or restore commands: SL3.7b, SL3.8a and SL3.8b add those users.
   • Approach: Use the existing private-directory and file-lock helpers from the CLI's store. Keep the layout fixed and publish a completed temporary directory with one rename; do not build a database, transaction log, restored-VM index, reconciliation pass or generalized lock manager.
   • Done when:
     • A valid snapshot name maps to a private directory and a separate exclusive-lock path.
     • A published named snapshot contains exactly the three required entries and opens as a strict snapshot.
     • Published snapshot entries cannot be modified through the store.
     • A restored sandbox record round-trips the name of its source snapshot.
   • Needs: SL3.2b, in nvx-rs slimming 3.1.3: the CLI keeps its own sandbox store #1108; SL2.12b, in nvx-rs slimming 2.3.2: snapshots have one strict format, and a capture finishes into it #1102.
   • Estimate: 150 core lines, 2 counted files. Past 300 core lines, stop and ask before continuing.

2. SL3.7b: snapshot capture creates a named snapshot.

   • Objective: Users need snapshot capture to create a strict named snapshot through the new VM and NVXC APIs. The command must publish only a completed capture and leave interrupted or timed-out attempts for normal launch recovery, never resumption.
   • Contents: The command, on host::vm::create with boot.capture, whose command line holds nvx_sandbox=1, so that the shell /init hands the capture VM to nvx-init's capture entry (SL7.7a), NVXC's capture request (SL4.2), Process::wait and snapshot::finish_capture: the Exited proof goes to finish_capture; if the wait's deadline passes first, the command stops the VM and never finishes that capture. The capture VM goes through the store's launch journal, so after an interrupted capture the next command's recovery ends its VM and removes its directory; a capture is never resumed. Once finish_capture returns, the command publishes the named snapshot: it moves only key.bin, snapshot.json and openvmm/ into the store, which keeps them immutable; the capture VM directory's other files stay outside the snapshot, and the command then removes that directory.
   • Scope:
     • The CLI snapshot command, capture orchestration and fake-backed CLI tests.
     • A blockless capture VM created with boot.capture and nvx_sandbox=1, then driven by ControlSession::capture.
     • Process::wait supplies the Exited proof to snapshot::finish_capture; a missed wait deadline stops the VM and never finishes the capture.
     • After finish_capture, only key.bin, snapshot.json and openvmm/ move into the named store, then the capture VM directory is removed.
     • The capture uses the ordinary launch journal, so the next command ends an interrupted VM, removes its directory and publishes no snapshot.
   • Not in this PR:
     • Resuming or finishing an interrupted capture: the user starts a new capture.
     • A durable capture transaction beyond the existing launch journal: no separate in-flight record is kept.
     • Capturing a running layered workload: the capture VM is blockless and has no layered root.
     • Moving logs, capabilities or other VM-directory files into the snapshot: the strict format has exactly three entries.
     • Restoring the named snapshot: SL3.8a and SL3.8b add restore commands.
   • Approach: Compose vm::create, the existing launch journal, NVXC capture, Process::wait and snapshot::finish_capture. Publish through the small store from SL3.7a only after exit and validation; do not add resumable workflow state, a capture reconciler or a second snapshot format.
   • Done when:
     • A capture publishes exactly key.bin, snapshot.json and openvmm/, opens strictly and removes its VM directory.
     • A VMM that misses the exit deadline is stopped and no capture is finished.
     • Recovery ends an interrupted capture VM, removes its directory and publishes no snapshot.
   • Needs: SL3.7a, above; SL2.14, in nvx-rs slimming 2.3.2: snapshots have one strict format, and a capture finishes into it #1102; SL3.3b, in nvx-rs slimming 3.1.3: the CLI keeps its own sandbox store #1108; SL4.2, in nvx-rs slimming 3.2.1: NVXC asks for a capture and activates a restore, and a blocking driver restores #1113; SL7.7a, in nvx-rs slimming 3.3.3: nvx-init captures and restores, and boots the new launches' layered roots #1117; SL7.8a, in nvx-rs slimming 3.3.3: nvx-init captures and restores, and boots the new launches' layered roots #1117.
   • Estimate: 220 core lines, 3 counted files. Past 440 core lines, stop and ask before continuing.

3. SL3.8a: snapshot restore starts a sandbox from a named snapshot.

   • Objective: Users need snapshot restore to create a managed sandbox from a named strict snapshot without concurrent link changes corrupting restore startup. The restored sandbox remains recoverable through the ordinary launch journal and records which snapshot supplies its view.
   • Contents: The command, on host::vm::create with from: Some and the CLI's blocking restore driver beside host::session, under the snapshot's exclusive lock, held from create through the peer-verified restore-ready event or the VM's verified exit. The restored sandbox's record names its snapshot, and deprovision holds that snapshot's lock while it removes the sandbox's view. A restore whose command dies can't complete; the next command's recovery ends it, like an interrupted launch. Its tests check that a restore's own network policy reaches the guest: its DNS and its announcer.
   • Scope:
     • The CLI's snapshot restore command, restored-sandbox record and deprovision path, with fake-backed CLI tests.
     • vm::create with from: Some followed by the CLI's blocking restore driver, using the restored sandbox's workload and mapping table.
     • The snapshot's exclusive lock from create through peer-verified restore-ready or verified VM exit.
     • The sandbox record names its snapshot, and deprovision holds that snapshot's lock while removing the restore view.
     • The restore's own network policy reaches the guest, including its DNS and announcer.
   • Not in this PR:
     • Durable in-flight restore records or reconciliation: a dead command cannot complete activation, and normal launch recovery ends its VM.
     • An index of restored VMs per snapshot: the sandbox's own record is the only association.
     • Shared restore locks or parallel startup from one snapshot: one exclusive lock serializes the link-sensitive interval.
     • Resuming a restore whose command died: the next command cleans it up.
     • One-off run --restore-snapshot: SL3.8b adds that path.
   • Approach: Reuse managed sandbox creation, its launch journal and recovery, then call the blocking restore driver while holding the snapshot store's single lock. Add the snapshot name to the existing sandbox record; do not create a restore ledger, background reconciler or snapshot-to-VM index.
   • Done when:
     • Named snapshots restore with each supported image format and upper.
     • Concurrent restores of one snapshot wait for the same exclusive lock.
     • deprovision holds the snapshot lock while it removes the restored sandbox's view.
     • A command killed before restore-ready never completes, and the next command's recovery ends its VM.
     • The restored guest receives the restore's DNS and announcer policy.
   • Needs: SL3.7b, above; SL3.5b, in nvx-rs slimming 3.1.5: the sandbox lifecycle runs on the new interface and nvx-init #1110; SL4.3, in nvx-rs slimming 3.2.1: NVXC asks for a capture and activates a restore, and a blocking driver restores #1113; SL7.7b, in nvx-rs slimming 3.3.3: nvx-init captures and restores, and boots the new launches' layered roots #1117.
   • Estimate: 250 core lines, 3 counted files. Past 500 core lines, stop and ask before continuing.

4. SL3.8b: run --restore-snapshot restores a one-off VM from a strict snapshot.

   • Objective: run --restore-snapshot currently passes an arbitrary OpenVMM snapshot through to OpenVMM. This PR makes it restore the CLI's strict named-snapshot format through the same controlled path as snapshot restore, with the one-off run's own network policy.
   • Contents: The option, on the same path as snapshot restore, which installs the network options as the restore's own network policy, with its DNS, egress, forwards and published listeners. run drops --restore-network-policy, which dev added to select that for a raw snapshot, since it refuses raw snapshots. A raw OpenVMM snapshot is refused until NVX can snapshot blockless VMs.
   • Scope:
     • The CLI's run restore option, its option validation and fake-backed CLI tests.
     • Strict snapshots opened through the CLI and restored through the same create, lock and blocking restore-driver path as snapshot restore.
     • The run's DNS, egress, forwards and published listeners become the restore's own network policy.
     • Removal of --restore-network-policy, whose raw-snapshot selection role is no longer needed.
     • A clear refusal of raw OpenVMM snapshots.
   • Not in this PR:
     • Continued raw snapshot pass-through or automatic conversion: strict snapshots are the only accepted input.
     • Snapshots of blockless VMs: that capability is a later OpenVMM and NVX follow-up.
     • A second restore implementation for run: it uses the path added by SL3.8a.
     • Durable restore records, restored-VM indexes or restore reconciliation: the snapshot store has none.
     • Changing network policy payloads in NVXC: OpenVMM installs the policy and activation carries the guest-applied state.
   • Approach: Route the existing option into SL3.8a's strict restore path and reuse the normal network-option lowering. Delete the raw pass-through switch instead of preserving two meanings; do not probe arbitrary snapshot layouts, convert formats or add compatibility modes.
   • Done when:
     • run --restore-snapshot restores a strict snapshot with its DNS, egress, forwards and published listeners.
     • A raw OpenVMM snapshot is refused before launch.
     • CLI tests that covered raw pass-through now cover the strict path and the removed --restore-network-policy option.
   • Needs: SL3.8a, above; SL3.4a2, in nvx-rs slimming 3.1.4: run uses the new interface and the CLI's own guest tokens #1109.
   • Estimate: 150 core lines, 3 counted files. Past 300 core lines, stop and ask before continuing.

Tests. A capture leaves exactly key.bin, snapshot.json and openvmm/ in its private named snapshot directory, which opens as a strict snapshot, and removes the capture VM's directory; then restores with each image format and upper. A capture whose VMM doesn't exit by the deadline is stopped and stays unfinished. An interrupted capture's VM is ended, and its directory removed, by the next command's recovery, and no snapshot is published. Concurrent restores of one snapshot wait for each other's lock, and deprovision of a restored sandbox holds its snapshot's lock while it removes the view. A restore whose command is killed before restore-ready never completes, and the next command's recovery ends its VM. run --restore-snapshot restores a strict snapshot and refuses a raw OpenVMM one; today's CLI tests of the raw pass-through are rewritten for that.

Done when: every PR above has merged, with dev green.

Supporting typed blockless snapshot work

The following are separate supporting changes for the strict one-off restore path, not an instruction to hide their library/guest changes inside SL3.8b's CLI delta:

• Typed strict snapshot support: represent genuine zero-block snapshots explicitly in capture configuration, authoritative strict metadata/key validation, compatibility checks and VM preparation. Determine mode from validated metadata/block inventory, never from a missing caller image, informational snapshot.json, invented geometries or a fabricated layered activation record. Preserve the fixed strict entries, owner-private immutable inputs, layered checks and existing layered key encoding.
• One shared restore driver: consume that typed mode in the existing checked host/session/guest restore path. Retain layered transaction equality, resource/root checks, MAPS/EXEC ordering, peer/process verification, cancellation, exit and cleanup. Blockless repair uses the existing untiered packet semantics; DNS and listener repair must finish before the native host-input gate releases. An interrupted repair must fail closed rather than repeat irreversible effects.
• Preserve the correct RESET/reconnect/capture-entry ordering, and the snapshot lock from create through verified restore-ready or verified VM exit, including view removal and interrupted-command recovery.
• Keep raw snapshot acceptance/conversion, a second restore implementation, a durable restore index/reconciler, and speculative native/protocol changes out. Final user-facing parser and run integration remain SL3.8b. Exercise malformed/mismatched modes, interrupted repair, network application, reconnect ordering, cancellation and verified exit while retaining layered behavior.

The checkpoint comment below identifies the two supporting branches independently. Their implementation checkpoints do not imply completed qualification.