[givethesourceplox]

What and why

Ocarina's first 3D load makes CPU-only tiled texture storage GPU-resident alongside private Metal textures. Scanning registered descriptors can also recreate zero-filled GPU textures for finalized objects whose storage has already been reused.

This keeps the existing raw-address table and shader ABI, but makes residency follow NVN address exposure and actual GPU buffer bindings. Late exposure invalidates the table generation; virtual mappings and capture replay remain conservative. Storage validation no longer calls the pinning address resolver. Retired descriptors preserve existing backing, CPU uploads and linear/sRGB aliases, but do not recreate lost GPU storage.

The same allocation preflight rejects incompatible texture classes while preserving cube faces' 2D-array backing. Compressed IMAGE textures retain read-only usage, allowing the separate mip-reduction work to apply. A setter-only declaration for the existing OS-27-guarded MetalFX offsets allows the host to compile with Xcode 26.5 headers; its runtime selectors are unchanged.

Reference finding. Related: #1281, #1326, #1299. This does not replace #1360's pool-table capacity fix or duplicate #923, #1225, #1308 and #1319.

Checked

On Apple M1 Pro, 16 GiB, macOS 26.5.2, Xcode 26.5:

• Exact branch: t_raw_residency, 1,079 checks, and t_cpu_tex --metal, 56 checks, pass with Metal API validation. These cover 1,024 retired GPU descriptors over reused storage, late pool/buffer/texture address exposure, CPU uploads and command snapshots, cube-array compatibility, compressed image usage and retired linear/sRGB aliases.
• LLVM 23.1.2 static analysis of the changed production code and fixture: no findings above the existing baseline.
• Documentation tests: 11 pass. Chain tests: 17 pass. No shader-chain tools, libraries or game profile data change; no full game shader rebuild was performed.
• Gameplay measurement: Ocarina of Time 0400486024DEC000 v131072, short loads into Link's house on the existing integration stack, including [WIP] The Legend of Zelda: Ocarina of Time (Switch 2, 0400486024DEC000, v0, SDK 22.2.8) runs on the Mac through the title movie into Kokiri Forest #1299/Raw global memory's pool table grows with the pools: pools past 4,095 were left out and hung the GPU in Ocarina of Time #1360 and other open Ocarina fixes. This exact upstream-base branch has fixture validation, not standalone gameplay validation.

Residency-set inventory, MiB (different short runs; not an isolated FPS benchmark):

	Before address-exposure tracking	After
Shared pool buffers	5,469	2,123
Textures	3,513	3,561
Total residency set	9,179	5,881

The after-run still reports about 9,080 MiB Metal allocations and 9,635–9,785 MiB process resident memory. These are different accounting measures: 5,881 MiB is the residency-set inventory, not total app RAM. Gameplay remains below 30 FPS, with roughly 37–40 ms median frame time in the sampled gameplay windows. No FPS, thermal or iPhone fix is claimed.

Limits: the existing 4,095-pool capacity remains on this base (#1360 addresses it); private texture copies and already pinned pools are not removed. No five-game regress.py check report or iPhone run is available. Cross-game address reachability and long-session behavior still need runtime coverage.

Docs

• Findings recorded in docs/reference/nvn-objects.md and docs/reference/shaders.md; symptom index regenerated.
• Shader chain unchanged; no chain-header update required.
• No game files, keys or extracted game data included.

[david-on-spring]

This overlaps two drafts of mine, opened at about the same time from the same Ocarina of Time measurements:

• Raw global memory's pool table lists only the pools the game took a buffer address in: every pool was wired for it, which slowed Ocarina of Time's frames to 60-65 ms #1394 lists only the pools the game took a buffer address in. It marks them from nvnMemoryPoolGetBufferAddress, nvnBufferInitialize and nvnTextureGetTextureAddress, and doesn't list the rest in the raw table or make them resident. tex_storage_live uses a lookup that doesn't pin, and texture-only uploads read through a transient buffer. Your exposure tracking covers the same ground and more: GPU buffer bindings, and late exposure invalidating the table.
• Profile key pool_skip_retired: pool tables give a finalized texture's ID the dummy instead of making its texture again (Ocarina of Time out of GPU memory at a scene change) #1393 gives a retired ID that has no view the dummy in pool tables, instead of making its texture again. It's a profile key, off by default. Your "do not recreate lost GPU storage" covers this too.

If reviewers would rather take this one, I'm happy to close mine. Data points from ours, on Ocarina of Time on a 16 GB M4:

• Leaving texture-only pools out took frames in the house from 60 ms to about 26 ms.
• Skipping retired IDs removed the out-of-memory at the house → forest change: 25 minutes with no error, peak GPU allocation about 12 GB instead of 16 GB.
• PucaVaz measured the second on an M4 24 GB in Profile key pool_skip_retired: pool tables give a finalized texture's ID the dummy instead of making its texture again (Ocarina of Time out of GPU memory at a scene change) #1393: 11.4 GB against 13.2 GB at the door.

Drafted with Claude; reviewed by me.