[Pedro Henrique Penna (ppenna)]

Summary

Commit d5888a6 moved the filesystem-shares microVM scenario from two shares with separate virtio-fs tags to three children of one aggregate on the microVM's single virtio-fs slot, because the pinned OpenVMM no longer offers a second slot. The "Concurrent-share coverage" paragraph in doc/design/validation.md still described the old two-share scenario. This PR rewrites that paragraph to match the current scenario. It changes no other text.

Changes

doc/design/validation.md, Concurrent-share coverage paragraph:

Old statement	Corrected statement	Evidence
Attaches a read-write workspace and a read-only tool cache, "each with its own tag"	Attaches a workspace, a tool cache, and a data directory as children of one aggregate on the single virtio-fs slot, each with its own denied paths	_aggregate_arguments and run_filesystem_shares in scripts/nvx_tools/microvm_tests.py (--mount-aggregate /run/nvx/shares plus three --mount-child options); filesystem-shares.sh checks for only the 0xd0001000 slot and virtfs_aggregate=1
(not covered)	The data directory hides its root except for one directory and one file, and only that file is writable; the guest cannot create names in the hidden root	--mount-deny, --mount-allow, and --mount-write in _aggregate_arguments; filesystem-shares.sh exit codes 54-57 and 63-67
"with the tool cache's tag remounted read-write inside the guest, EROFS from OpenVMM for every mutation"	Through the aggregate's read-write, root-only mount, OpenVMM returns EROFS for mutations of the tool cache, keeps denied paths hidden, and refuses hard links between children	filesystem-shares.sh exit codes 48 and 68-87
Rejects "three shares, nested guest targets, nested host directories, and ambiguous denied paths before boot"	OpenVMM rejects a repeated --mount, --mount beside an aggregate, overlapping children, and a relative denied path before boot	The repeated-mount, overlapping-children, mount-and-aggregate, and relative-deny cases in run_filesystem_shares
"round-trips both shares through a snapshot whose restore must supply both in capture order"	A snapshot round-trips an open workspace file; a restore that drops, swaps, or renames a child, or offers a single --mount, fails before the guest resumes	filesystem-shares-snapshot.sh (the /workspace/journal file descriptor); the missing-share, swapped-shares, renamed-share, and single-mount cases, which _expect_process_failure runs with the post-restore marker forbidden

OpenVMM pin: 7bf0ee28b826374a2d386067df0456b81bcae818. This is a design chapter, but the change describes the NVX-owned test scenario and does not change any claim about OpenVMM behavior.

I kept the paragraph's existing name, "Concurrent-share coverage", and its level of detail rather than restructuring the chapter.

Follow-ups

These were left out to keep this PR to one topic or to avoid conflicts with open PRs:

• scripts/setup/README.md is documentation outside doc/. Moving it would require link edits in doc/setup.md and doc/ci.md, which open PRs test-microvm: pause and resume a microVM through OpenVMM state control #405 and Adopt bind-once microVM image slots #406 change, and scripts/test_nvx_tools.py references its path. It should move after those PRs land, along with a matching test update.
• doc/openvmm-upstream-roadmap.md is a dated planning snapshot. It records fork tip 2728f33ea, but OpenVMM is now pinned at 7bf0ee28. It needs either a refresh of the commit-to-PR mapping, which is far larger than this PR's budget, or a clear statement of the date it reflects.

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 repository checked every relative link and anchor in doc/design/validation.md and in the files that link to it (doc/design.md, doc/contribute.md). It also confirmed that the changed file has one H1 and balanced code fences, and that doc/design.md links every chapter in doc/design/. Result: OK.
• git diff --check: clean.
• python scripts\nvx.py verify: passed.
• The only changed path is doc/design/validation.md, so CI treats this PR as documentation-only.

[Copilot]

🟢 Approval recommended

The documentation accurately reflects the referenced implementation and test behavior.

0 open findings

What changed in this PR

Updates validation documentation to accurately describe the current aggregate filesystem-shares microVM scenario.

Changes:

• Documents three shares on one virtio-fs aggregate.
• Describes access-policy, hard-link, rejection, and snapshot-restore coverage.

File	Description
doc/​design/​validation.md	Aligns concurrent-share coverage with the current test scenario.

🧠 Review effort: Balanced

---

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