doc: define the single-slot host filesystem boundary

[Pedro Henrique Penna (ppenna)]

Summary

Fill the host-filesystem configuration gap in the configuration boundary. The chapter was last edited at NVX commit 5f5bd9f3d, before the aggregate and regular-file export changes reached the OpenVMM pin.

Keep this to one architecture-level topic in one document: explain how multiple host paths fit the fixed device inventory, and make the dormant-slot restore exception explicit. Link to the existing filesystem ABI instead of repeating its option syntax, export-policy details, or compatibility rules. No implementation or gitlink changes.

Base: origin/dev at a5df986e5e606a82add90646fb6a3f9de0a2ec69.

Changes

• State that host sharing uses the single fs:microvm0 slot, with either --mount for a directory or --mount-aggregate and --mount-child for named directory or regular-file children. Evidence: fixed filesystem inventory, CLI arguments, and file-child construction tests.
• State that the aggregate root is read-only and each child has its own access mode. Evidence: synthetic-root and child-access tests.
• Clarify that restore may bind a new directory export to a captured dormant filesystem slot, rather than suggesting that restore only supplies already-required attachments. Evidence: restore attachment validation. That code permits only a single-directory request for a dormant slot; active exports remain bound to their captured contract.

OpenVMM revision

2130f24b5a51561cc6224fe5a0aff93cb121ac32 (unchanged).

The previous pin when this chapter was last edited was 3796991d52ce07d88b5dba25e4d1e8deaff6fd95; the intervening pinned commits were inspected, and the claims above were checked against the current source and tests, not the OpenVMM Guide or PR descriptions.

Follow-ups

• Move the environment bootstrap guide from outside doc/ in a later run. Conservatively defer that relocation because its inbound links are in the CI and setup guides, which open PRs test-microvm: pause and resume a microVM through OpenVMM state control #405 and Adopt bind-once microVM image slots #406 modify. All files changed by open PRs were left untouched.

Validation

• python -m unittest scripts.test_nvx_tools.CliTests scripts.test_performance.PerformanceTests - PASS, 117 tests, OK (skipped=1).
• Throwaway Python checker outside the repository - PASS, all 85 relative links and anchors in the changed document and its two inbound-link documents resolve; the changed file has exactly one H1 and balanced code fences; doc/design.md links all 16 design chapters.
• git diff --check - PASS.
• python scripts/nvx.py verify - PASS, both during setup and after editing; the OpenVMM checkout matches the recorded gitlink.
• Full maintainer diff review - PASS, one coherent topic, one Markdown file, 10 added lines and one removed line; every added assertion traced to the pinned source/tests, and every changed path matches the documentation-only boundary.

No builds or hypervisor runs were needed for this documentation-only change.

[Copilot]

🟡 Changes recommended

The restore wording omits the snapshot capability required to bind a new filesystem attachment.

1 open finding

• Document restore attachment limits for older snapshots · New

What changed in this PR

Defines the single-slot host filesystem configuration boundary and restore behavior.

Changes:

• Documents single-directory and aggregate HostFs exports.
• Clarifies dormant-slot restore attachment behavior.

File	Description
doc/​design/​configuration-boundary.md	Documents HostFs slot configuration and restore semantics.

🧠 Review effort: Balanced

---

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

[Copilot]

🟢 Approval recommended

The documentation accurately reflects the pinned OpenVMM implementation and existing filesystem ABI.

0 open findings

1 resolved since last review

• Document restore attachment limits for older snapshots

🧠 Review effort: Balanced