[socram03]

What and why

Busy OoT scenes can spend more time searching pipeline archives than rendering. When the hybrid demand-build table is full, draws keep using a pulling stand-in and repeatedly scan every archive for the same missing layout-specific base. Successful bases are cached; absent ones are not.

Cache those misses under the existing base key and lock. A repeated non-compiling probe returns immediately, while demand compilation can still build the base and a completed positive result always wins. The archives are loaded once, so these entries remain valid for the process and are never persisted. See the reference entry.

In earlier OoT v131072 city runs, CPU translation fell from ~114 to ~6.4 ms/frame and failed archive searches from 9,208 to 5 per 300 frames; I saw roughly stable 30 FPS afterward. Those runs used bd979ced3ae6 with local frame-step/packaging changes. Camera, route and cache warmth differed, so this is supporting evidence, not a controlled benchmark on the PR base.

Checked

On Apple M5 / macOS 27.0.1 / Xcode 27.2, the host builds and the archive suite passes 242 checks plus its fresh-process test with Metal validation. The regression verifies one scan for 100 misses, independent layout keys and later successful compilation. Its two lookup-count assertions fail on the unmodified PR base, 028a2631.

Full-suite failures and coverage limits

• The full Metal suite encountered two failures also reproduced on the base: t_present_crop SIGSEGV and an intermittent t_feedback timestamp assertion. Three candidate feedback reruns passed.
• LLVM 23.1.4 checked all 259 sources: candidate and base have identical 248-finding multisets. The committed 240-finding ratchet fails on both, including the base CI run. Pinned Ruff/Pyright pass with zero new or stale findings.
• Python tools: 1,392 tests, 23 skips, one environment-switch-table failure. CI also reports six Xcode-fixture errors because its synthetic RomFS.img is absent. Both failure types reproduce on the unmodified PR base (028a2631), locally and in the base CI run. Documentation checks pass.
• regress.py impact names Breath of the Wild, Tears of the Kingdom and Pokémon Scarlet; 149 profiles lack manifests. Those three, OoT and Wonder were selected for coverage, but only the manual OoT build is available, and regress.py check cannot discover its layout. No fresh harness gameplay/shader result is claimed.

Docs

• Reference entry, game note and regenerated symptom index.
• No shader-chain tool changed.
• No game files, keys or extracted data in the change or attachments.

[sleepyeyedjoe]

Tested on a MacBook Pro M4 Pro (24 GB, macOS 27.0.1), Ocarina of Time 0400486024DEC000 v131072, handheld mode, real play (not a replay). It fixes the Castle Town drop here.

Setup

• My app is main 1794a35 + Game-mode draw passes hold the next pass's task and mesh shaders until their fragments are done #1707 + position.z one ULP down against a surface's own stored depth: fixes Ocarina of Time mist specks #1742 + Raw global memory loads through one pointer resolve its pool once, and the pool table search is a loop: Ocarina of Time's colour-pass mesh shaders stop looking up the pool table per word (chain 723dc3a3e17d) #1752, with Honor NVN event dependencies across guest queues #1245's host (ea0c98d reverted). Chain 058136f61e9e.
• I cherry-picked only e1e2298 onto it. nvn_mtl.m merged cleanly; only the game README conflicted (kept mine). Host-only rebuild.
• t_pso_archive on that base: 242 checks, 0 failed.
• Same settings in both sessions: present snapshots on, DM_FPS_HOLD=off.

Before (first visit to the Market, without the PR)

• Entering the Market, the frame step collapsed to about 12 fps. In the worst period, frame time p50 was 84 ms and p95 118 ms, against GPU p50 26 ms and submit+present 0.8 ms.
• pipelines up to frame 7800: archive lookups found none 49,044 / 17,079 ms; draws with a hybrid pipeline 212,820; in flight 384 for the rest of the session.
• Main thread 854 ms/s, against 391 ms/s in Hyrule Field just before.
• Game time ran at 0.605 of real time over that stretch.
• It recovered by itself after about 3 minutes, as the queued bases were built.

After (second visit, with the PR)

• Frame time p50 16–20 ms and p95 20–32 ms over about 75 s in the Market (frames 1200–5400), GPU p50 12–16 ms.
• Found none per 300 frames: 427 in the period of the scene load, then 5–57.
• The table was still full (in flight 384) and the hybrid draws were still 40k–158k per 300 frames. So the saturated case your PR describes was hit, and the repeated probes were gone.
• Main thread 440–600 ms/s. Game time 1.000 of real time.

Caveat

• This is not a controlled A/B. The second visit started with 489 more pipelines prepared before the first frame (the first visit's builds, through pso_user.tsv). That explains part of the lower GPU time.
• The found-none count with a full table is the direct effect of the PR. It fell from ~49k to tens per 300 frames.
• I tried an A/B replay of a scene load (old and new host). Both stalled the same way. The replay ran no prepare step before the first frame, so its pulling bases were still pending and no draw used a stand-in. It never reached the code this PR changes.

[seedds]

Landed on main as 2f131ed, with you credited as co-author. Thank you for the diagnosis and the fix, and thanks to sleepyeyedjoe for the M4 Pro run, which hit the full-table case directly.

Your cache went in as you wrote it, with two refinements:

• A miss is recorded whenever the archives lack the base, whether or not the caller compiles. If a compile then fails, later non-compiling asks still skip the search.
• A compiling build whose base is a known miss goes straight to the compiler. Each build the full table turned away no longer searches every archive file once more before compiling. The test checks this too.

The docs are shorter: the game note keeps one "Resolved" line under Frame rate with both testers' measurements and their limits, and the reference entry is now Archive searches repeated while the build table is full.

Checked: check_t_pso_archive on main passes 338 checks plus the 6 fresh-process tests. Without the cache, its lookup-count checks fail.