[Pedro Henrique Penna (ppenna)]

Summary

The "Snapshot identity and admission" section of the snapshot sharing and host storage design chapter had the implemented behavior backwards. It called a caller-authenticated storage generation "the common trusted-storage path" and whole-file SHA-256 "optional", and it said restore never rereads block bytes. In the pinned OpenVMM, SHA-256 is the default: capture hashes every bound sandbox block, and restore hashes them again. Storage generations are opt-in. The section also mixed implemented behavior with storage control-plane and transport guidance that is not implemented, without marking that guidance Proposed.

This PR corrects the section to match the implementation and moves the unimplemented guidance under a Proposed subsection. Other chapters, such as snapshot-and-restore.md and machine-and-device-abi.md, already describe this correctly, so the new text links to them instead of repeating them.

Changes

doc/design/snapshot-sharing-and-host-storage.md, "Snapshot identity and admission":

Corrected statement	Evidence
sha256 is the default identity policy. generation applies only with --snapshot-block-identity generation --snapshot-generation-id <32-HEX>.	openvmm/openvmm/openvmm_entry/src/cli_args/microvm.rs (SnapshotBlockIdentityCli has #[default] Sha256; capture validation runs unwrap_or(Sha256) and requires the generation ID exactly when generation is selected)
Under sha256, capture hashes each bound block, and restore hashes each one again and rejects a mismatch. Before, the section said restore "does not reread every logical block byte".	openvmm/openvmm/openvmm_entry/src/storage_builder/microvm.rs (file_sha256 at capture and in restore_snapshot_block_contract); openvmm/openvmm/openvmm_helpers/src/snapshot/microvm.rs ("snapshot sandbox block topology or identity doesn't match the requested machine")
Every bound block in a snapshot uses the same identity policy. Generation mode requires one shared nonzero generation and does not read the blocks.	openvmm_helpers/src/snapshot/microvm.rs ("mixed identity policies", "do not share one storage generation", nonzero generation checks); Guide snapshot_format.md
OpenVMM does not authenticate the generation. The storage owner must keep it immutable and bound to the exact files.	cli_args/microvm.rs doc comment; Guide user_guide/openvmm/snapshots.md ("it does not authenticate bytes by itself")
Generation authentication by a publisher or control plane, SHA-256 during transport, ETag binding, upload ordering, and import admission are now under Proposed. NVX does not import or transport snapshots.	doc/design/snapshot-and-restore.md ("standalone NVX snapshot import are not supported"); generation IDs come only from the caller's --snapshot-generation-id (cli_args/microvm.rs)

The existing text on sealed-snapshot immutability, clones, and the single-use resume claim is unchanged; it matches resume.claim handling in openvmm_helpers/src/snapshot/restore.rs.

OpenVMM SHA: f4566bab0a30324de0a2ac292a65d0081ba319e0 (the pinned openvmm gitlink at origin/dev dd9744a8b490599a411152a7359f68f2798f9baf).

Follow-ups

These are out of scope for this one-topic PR:

• doc/openvmm-upstream-roadmap.md maps fork commits only up to 2728f33ea. The current pin is 134 fork commits further on, including time ABI, CPU profile, multi-share virtio-fs, generation-bound snapshot, and egress selector work. Remapping them into the upstream PR plan needs maintainer judgment about classification.
• scripts/setup/README.md is contributor documentation outside doc/. Moving it means updating links in doc/setup.md, and open PR Adopt bind-once microVM image slots #406 already touches doc/setup.md.
• On doc: add CPU profiles and the RAM overlay to the configuration boundary #454, review asked that doc/design/time-abi.md accept auto on restore so it agrees with configuration-boundary.md. That file is still touched by open PRs test-microvm: pause and resume a microVM through OpenVMM state control #405 and Adopt bind-once microVM image slots #406, so I left it alone.

Validation

• python -m unittest scripts.test_nvx_tools.CliTests scripts.test_performance.PerformanceTests: Ran 110 tests, OK (skipped=1).
• A throwaway link checker, kept outside the repo, covered the changed file and every Markdown file that links to it, directly or through doc/design.md (22 files). Every relative link and anchor resolves, the changed file has one H1 and balanced code fences, and doc/design.md links every chapter in doc/design/. Result: OK.
• git diff --check: clean.
• python scripts/nvx.py verify: source tree and submodule metadata are consistent.
• The diff changes only doc/design/snapshot-sharing-and-host-storage.md, so CI classifies it as documentation-only.

[Copilot]

🟢 Approval recommended

The documentation accurately reflects the referenced implementation and existing design chapters.

0 open findings

What changed in this PR

Corrects snapshot block identity documentation to match OpenVMM’s implemented behavior.

Changes:

• Documents SHA-256 as the default capture and restore policy.
• Clarifies opt-in generation identity semantics.
• Marks unimplemented storage and transport guidance as proposed.

File	Description
doc/​design/​snapshot-sharing-and-host-storage.md	Corrects snapshot identity and admission behavior.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.