Add design proposal: live memory resize for macOS (vz) VMs

[rgarcia]

Summary

Design proposal (RFC) for Live memory resize for macOS (vz) VMs under Apple's Virtualization.framework (the vz hypervisor) on Apple Silicon.

• Documents what "live memory resize" actually means on Apple's Virtualization.framework today: the vz traditional balloon can only reclaim within [floor, boot_size] (Code-Hex/vz v3 exposes only SetTargetVirtualMachineMemorySize/GetTargetVirtualMachineMemorySize; memorySize is fixed at NewVirtualMachineConfiguration), so growing above boot requires sizing the boot ceiling at VM-creation time.
• Proposes a memory_ceiling knob threaded through ShimConfig so a VM boots at its ceiling and is balloon-inflated down to its baseline at startup, turning balloon deflate into headroom-on-demand without a reboot. The pressure-driven resize loop reuses the existing active_ballooning controller, pressure signals (lib/guestmemory/pressure_darwin.go), and protected_floor rather than inventing new knobs.
• Cites Tart as prior art for static memory sizing with a minimum-resources floor (Sources/tart/VMConfig.swift setMemory + memorySizeMin; VM.swift:334 configuration.memorySize), adopts the floor-guard pattern (mapping it to protected_floor), and diverges by adding a per-VM ceiling and a live grow/shrink loop driven by host pressure.
• Specifies config/API changes, Go sketches matching hypeman's darwin build-tag conventions, platform constraints (macOS version gating, Apple Silicon, APFS/host-RAM ceiling math), a testing plan extending guestmemory_darwin_test.go, risks/alternatives, milestones, and open questions.
• Read/investigation deliverable: a standalone design doc grounded in concrete file:line refs in both hypeman and Tart; no code changes.

Notes

• This PR adds a design document under docs/proposals/; it is documentation only, with no code changes.
• It references Tart, an open-source VM toolset built on the same Virtualization.framework, as prior art for design comparison.
• Opening as a draft to gather feedback on the approach before any implementation.

🤖 Generated with Claude Code