How to query purgeable space?

This is a difficult topic. Ideally, you should check for free space (true free space) before allocating storage. You should also handle any failures to allocate storage. But as I understand it, the operating system is not going to free up storage until after a failure. It does that on its own schedule. All you can do is suggest the user try again later after freeing up more storage.

You seem to refere to your own installer. That is even more problematic. The idea is to distribute your apps in the Mac App Store, or at least using official package installers, or even zip downloads. In all these cases, it is Apple (or the user) that has to deal with the availble vs. free question. If you are injecting your software into the installation process, you are making it your responsibility.

Further complicating this is the Finder. It is only going to report "available" space. So when the user invariably complains that they have "plenty of free space", they are complaining about the App Store, an installer, or a download. If you assume this responsibility, they can now complain about your code and you now have to deal with it.

If you really want to do this, here is what you do:

1) Get a URL to the root mount point. If you are on Catalina, you may have to track down the data volume.

2) Call NSURL "getResourceValue:forKey:error:" on the URL using the key "NSURLVolumeAvailableCapacityForImportantUsageKey".

This is not quite what you asked, but I think it is all there is. There is an "NSURLVolumeAvailableCapacityForOpportunisticUsageKey". I really don't understand the documentation (in the header file) for these two entries. I have found that "NSURLVolumeAvailableCapacityForImportantUsageKey" is equivalent to the Finder's display of "available" space, which is what I was interested in. There is no guarantee that any of this is truly "purgeable" or ever would be.