feat: add Cloud Hypervisor filesystem write planner

docs/cloud-hypervisor-foundation.md

@@ -164,6 +164,36 @@ Temporary microVM workspace data lives under:
 With `--keep-containers`, AWF preserves this directory, the network namespace,
 and runtime diagnostics for investigation.
 
+### Write-policy planning (inert)
+
+[`src/cloud-hypervisor/filesystem-write-policy.ts`](../src/cloud-hypervisor/filesystem-write-policy.ts)
+plans how a `filesystem.allowWrite` allowlist would narrow validated exports. It
+maps each guest path to the canonical host path beneath the deepest matching
+export, rejects `..`, missing paths, and symlink escapes, and classifies every
+export as unrestricted, read-only, fully writable, or selectively writable.
+
+Read-only enforcement is a host-side property. Each plan entry therefore carries
+two modes: `hostRootMode`, the mode the host backing tree root is staged with —
+the read-only bind that `virtiofsd.ts` already builds for read-only exports —
+and `guestMountMode`, the flags of the guest virtio-fs mount. A selectively
+writable export reports `hostRootMode: 'ro'` with `guestMountMode: 'rw'`:
+mounting a composite tree read-only in the guest would also block its writable
+nodes, because virtio-fs submounts are attached through `d_automount` and
+`finish_automount()` calls
+`do_add_mount(..., path->mnt->mnt_flags | MNT_SHRINKABLE)`, so an announced
+submount inherits `MNT_READONLY` from its parent mount. The host VFS, not the
+guest mount flag, denies writes outside the overlays.
+
+Overlay paths are absolute but canonical in different senses: `guestPath` is
+lexically normalized, while `hostPath` is realpath-canonical and verified not to
+escape the export source.
+
+The planner only removes write access: it never widens a read-only export and
+never introduces a host path that an existing read-write export does not
+already cover. It is pure policy planning and is not yet wired into runtime
+execution — `filesystem.allowWrite` is still rejected for the Cloud Hypervisor
+runtime by [`src/filesystem-policy.ts`](../src/filesystem-policy.ts).
+
 ## Limitations
 
 The preview rejects configurations that weaken or conflict with its boundary,