[akshay4]

Stacked on #1391, and this is only its last commit. Happy for it to be folded in there instead.

What and why

With #1391, Ocarina of Time stops within minutes on a 24 GB Mac with the "GPU memory is nearly full" alert, while the GPU is well under its limit:

	At the stop
currentAllocatedSize	17.3 GB (18.4 GB with the stop raised)
Residency set	6.5 GB
Driver's In use system memory	7.7 GB peak
Metal's working set	18.2 GB

currentAllocatedSize counts each no-copy buffer in full however many cover the same pages. A small test put 50 buffers over one 64 MB region and it rose 3,200 MB. I haven't confirmed that overlap accounts for the whole gap in this game. docs/reference/memory.md already notes this counter reading 16 GB against 3.9 GB in vmmap.

With the stop raised past the working set, the refused commit was followed by InnocentVictim command buffer errors, so refusing can itself cause a failure.

The guard now reads the set's own size.

Trade-off: a large burst is seen one commit later, and the timer only knows the size at the last commit. #1393 reports real out-of-memory errors with 16 GB allocated on a 16 GB Mac, which this doesn't explain, so it needs trying on a smaller Mac.

Checked

• Tests: check_t_res_guard, both runs; test_docs.py, test_env_switches.py
• Games run: Ocarina of Time 0400486024DEC000 v131072, main with Metal compiles take -fbracket-depth=1024: two Ocarina of Time compute shaders nest 259 brackets #1357, GPU-written storage is tracked as ranges, so a pool that holds both kinds no longer leaves its CPU-written textures at zero #1390, A GPU memory guard before each residency commit stops the game instead of freezing the Mac #1391, A GPU-only pool's render targets share one placement heap: Ocarina of Time's 3 GB of render targets fit in 0.7 GB #1453 and Shared textures no live object resolves to are retired when GPU memory runs short: Ocarina of Time no longer freezes after the talk with Saria #1455 on top: about 49 minutes, 170,400 frames, Kokiri Forest and the Great Deku Tree. currentAllocatedSize about 20 GB, driver in use at most 9.5 GB, wired about 10 GB, no GPU errors. Four earlier runs on the same stack stopped at the guard.
• Devices and OS: M6, 24 GB, macOS 27.2. Not checked: other games, a smaller Mac.
• regress.py not run: only the guard's reading changes, and it has no effect below its levels.

Docs

• docs/reference/memory.md updated, docs_symptoms.py run
• No game files, keys or data extracted from a game

[PucaVaz]

Same gap on an M4 MacBook with 24 GB (Metal's working set 18,186 MB), main 75c1a8c with #1453, #1455, #1332 and #1446, Ocarina of Time from the autosave at Link's house: currentAllocatedSize jumps with the save load (2.7 GB at frame 1800, 10.4 GB at 2100, 14.9 GB at 2400) and reaches 17.4 GB on a 10-minute walk, while the residency set holds 4.9–5.4 GB and the footprint is 9–11.5 GB, with no swap growth and no GPU errors over about 20 minutes. The same load on lunks's #1360 build (before main's Ocarina changes) read 9.0 GB at 9.7 GB resident. Measurements in #1385.

[akshay4]

Moved onto #1391's latest head and re-ran t_res_guard, both runs. It still conflicts with main in front.h and front_mac.m, where #1391's alert meets front_gpu_lost. This commit doesn't touch those files, so that has to be sorted in #1391. The two extra ArrayBound findings over main are in the g_mrbuf code and are on #1391 too.