WIP: feat(macos): add a macOS build #966

Draft
mooki wants to merge 117 commits from mooki/Longshot:mac/add-macos-build into main
Member

Type: feat · Risk: medium · Tested on: macOS 26.7.1, Apple M4 Max (arm64; x86_64 under Rosetta) · Needs: Windows and Linux, any GPU (and one GPU on the mesh compute fallback)

Current revision: 594d5296 merges main a8a30c22 into the combined macOS head 6343f29e. The PR remains WIP: final game-build acceptance, Windows/Linux qualification and guide/UI review are still open. Work is paused after this push at the owner's request.

Why

Nobody can build or run LS on a Mac today. The builder takes the Linux route there, the host's POSIX layer is written for
Linux and x86, and the Vulkan renderer neither finds a driver on macOS nor works within what MoltenVK and Metal allow: shaders
Metal refuses, descriptor sets MoltenVK cannot push, a compiler service that dies under the game's giant programs, draws
MoltenVK draws differently or not at all, and a GPU budget that ran a 64 GB Mac out of memory. This PR is the macOS port: LS
builds on a Mac (natively on Apple silicon, and as x86_64 under Rosetta), packages a game folder for macOS 14.4 and later, and
plays on Metal through MoltenVK (KosmicKrisp opt-in), held in play for over 15 minutes on both routes. Two kinds of draw the Mac
work found missing on every driver are drawn here for everyone: indirect quad draws, and mesh count draws on GPUs that use LS's
mesh compute fallback. It replaces the macOS topic PRs #845-#852 (71 earlier PRs in all) with one PR; the commits stay one per
original change. See #420.

What changed

The build scripts get a Mach-O route and a packager; the host gets native Darwin memory, waits, faults, threads, control and
crash records; the renderer loads MoltenVK (or KosmicKrisp through LunarG's loader), budgets from unified memory, and works
around what MoltenVK and Metal lack, area by area below. Almost everything is behind __APPLE__ or a run-time gate on the driver
(dev.driver_id, vendor fixes, Profile flags); what changes on Windows and Linux is listed under Risks. The original
6343f29e series below contains 104 non-merge commits and 12 merges; 594d5296 additionally integrates main's newer
renderer, host, build and shared-tooling changes while preserving the Mac platform gates.

1. macOS host (was #845)

  • Was #454: the game-free runner knows macOS (tests/run_all.py: macos, its skip reasons and timing).
  • Was #477: arm64 host jumps and pause hints (host/posix/darwin_cpu.c).
  • Was #478: guest pages on macOS (host/posix/darwin_mem.c: a Mach reservation, exact zeroing, 4 KiB guest rules on 16 KiB pages).
  • Was #436: Darwin fault contexts on both CPU routes (darwin_fault.c, for win32_posix.c's fault bridge).
  • Was #437: waits and deadlines, one sequence word shared by the executable and the renderer (darwin_wait.c, darwin_wait_state.c).
  • Was #438: the Vulkan loader and device admission (gpu/vk/vk_loader.h, vk_main.cpp, host/posix/darwin_vulkan.c; RX_VK_LIBRARY).
  • Was #490: Mach threads, guarded fibers, restart and posix_spawn, memory counters, a Mach sampling profiler; on Linux, Discord
    IPC (host/discord_rpc.c) and the thread error paths (win32_posix.c) hardened.
  • Was #453: Mach-O build commands (nx2/darwin_toolchain.py, nx2/darwin_build.py; RX_ARCH); Windows' and Linux' arrays move
    into four functions unchanged, element for element (tests/build_flags_main.json).
  • Was #479: each Darwin helper classified, every library checked, the game folder carries relocated, signed copies
    (nx2/darwin_package.py, nx2/darwin_archive.py).
  • Was #455: the builder's memory gate on macOS (nx2/darwin_memory.py).
  • Was #456, #457: control bridge sockets (host/posix/darwin_control_sockets.c), and the control test's quit case.
  • Was #476: cache file reservations (F_PREALLOCATE in pipeline_cache_file.h, F_RDADVISE in vk_progcache.cpp).
  • Was #480: guest memory ownership on 16 KiB pages (darwin_guest_mem.c).
  • Was #492: vk_programs.cpp, vk_shader.cpp and the debug tools build on Darwin.
  • Was #511: crash records (hos_report_run.c, hos_crash_record.c).
  • Was #516: longshot_ctl sessions (scripts/longshot_ctl.py).

2. Vulkan on Metal (was #846)

  • Was #491: host imports pinned until their last Vulkan owner (gpu/vk/darwin_import.h, vk_memory.cpp); every platform: a
    startup that fails part-way unwinds (replay_start_rollback(), vma_startup_rollback()), vmaDestroyAllocator is a recorder
    drain boundary, import pools are moved, not copied; on Linux MessageBoxA and waveOutOpen checks.
  • Was #642: the unified-memory budget (gpu/vk/unified_budget.h, system_memory.h, vram_usage(); RX_VK_UNIFIED_BUDGET).
  • Was #653: Metal's shader cache folder (gpu/vk/metal_cache.h; RX_VK_METAL_CACHE_DIR).
  • Was #654: LunarG's loader with MoltenVK (the default) and KosmicKrisp (RX_VK_DRIVER; LONGSHOT_VULKAN_LOADER,
    LONGSHOT_KOSMICKRISP).
  • Fix 80a10018: test_darwin_renderer's fixture declares main's evicted_import_bytes (#223).

3. MoltenVK descriptor limits (was #847)

On MoltenVK a program a pushed set breaks gets an ordinary update-after-bind set (layout_pushes() in vk_draw.cpp); every
other driver pushes as before, and the SPIR-V and the caches are unchanged.

  • Was #643: storage buffer tables (vendor fix set_for_tables, RX_VK_SET_FOR_TABLES).
  • Was #644: programs that read a storage buffer's length (gpu/vk/spirv_lengths.h; set_for_lengths, RX_VK_SET_FOR_LENGTHS).
  • Was #645: stages with more than 8 storage images and storage texel buffers.
  • Was #646: stages past a Metal function's buffer, texture or sampler table; update-after-bind pools.
  • Fix b56a6cee: main's Linux pressure fixture includes spirv_lengths.h (#223).

4. The SPIR-V back end and guest spans on MoltenVK (was #848)

Each part is chosen by a Profile flag make_profile sets on Apple, or by alias_isolation (macOS); with them off every
module, layout and command is main's (the fixtures check it byte for byte).

  • Was #647: the segment planner for guest spans past one device allocation (gpu/vk/span_segments.h).
  • Was #648: piece arrays in the back end (RuntimeInfo::segmented).
  • Was #649: texel carrier codecs for ten formats MoltenVK cannot view (texel_codec.h; RX_VK_TEXEL_CODECS).
  • Was #658: guest buffers admitted per operation, over-cap spans imported as segments (macOS).
  • Was #662, #663: the segmented consumers' contract, then the consumers (span_xfer.h), and stand-ins for empty slots (null_dummies.h).
  • Was #674: null descriptors emulated in the back end (kProgramCacheFormat 3).
  • Was #675, #698: storage image reads kept in program order (MoltenVK; KosmicKrisp).
  • Was #676, #692: SPIRV-Cross's expression nesting bounded (msl_depth.cpp).
  • Was #693: control-flow nesting bounded at 128 (msl_scope.cpp).
  • Was #686: Rosetta host imports at whole 16 KiB pages, a refused import asked again only when its backing changes (import_hold.h).
  • Was #694: vertex stages run the guest's warp operations as one-lane warps.
  • Was #695: RX_VK_SPV_PROFILE, what the big modules are made of (log only).
  • Was #696: storage buffer tables searched in loops (RX_VK_GM_LOOP on MoltenVK and KosmicKrisp).
  • Was #697: local memory zeroed by a loop (RX_VK_LOCAL_ZERO_LOOP).
  • Was #787: giant mesh fallbacks' shape through the real back end (test only).
  • Port 8e3c5951: a stand-in clear not done in 5 s is waited for before its fence and pool go (the Mac-only part of #788);
    81eff678 keeps it inside #if defined(__APPLE__).
  • Fixes: 7f9a99fa (the profile fixtures where #694, #696, #697 and #698 meet), 74d8a42b (the segment fixtures take main's
    FlatMap c1_at, #231), 30627309 (main's Linux pressure fixture stands in for SegSig's SegEntry).

5. Precompile and pipelines on Metal (was #849)

Under the vendor fix compiler_service (MoltenVK and KosmicKrisp only) the preparation compiles no compute pipeline, the
precompile orders the work for Metal's compiler service, lets the title come while the last giants build behind the game, bounds
giants and heavy compiles, and retries a failed compile alone (gpu/vk/precompile_handoff.h, the precompile in vk_draw.cpp).

  • Was #650: a pipeline cache per preparation worker, every CPU; no saved pipeline cache on MoltenVK (worker_caches.h, prepare_workers.h).
  • Was #651: renderer threads start with a 16 MiB stack on macOS (gpu/vk/thread_stack.h).
  • Was #652: the precompile goes on behind the title; slow compiles named.
  • Was #664: compute pipelines left to the precompile; at most 4 giants in flight (seed_compute).
  • Was #665: giants held until the first frame, at QoS class utility; a failed giant retried alone.
  • Was #666: a dispatch's compile goes ahead of the giants and is retried alone (skip_log.h).
  • Was #667: RX_VK_METAL_ARCHIVE_DIR, Metal binary archives (metal_archive.h; off).
  • Was #669: giants start behind the game only while memory allows; a lost device said as one.
  • Was #681: RX_VK_LMEM_LOG (private_memory.h; log only).
  • Was #784: heavy compiles run alone.
  • Was #785: KosmicKrisp's compiles through the compiler service, as MoltenVK's.
  • Was #786: Metal's cache folder asked at the host's start, before SDL's window (host/posix/darwin_metal_cache.h).
  • Ports: e1965d56 (a never-ending compile holds the heavy ones back 240 s at most), 3c23a8e9 (slow-first: what an earlier run
    found slow compiles first), cb01f764 (metal_archive.h's notes).
  • Fix 30252cf5: Metal's compiler service out of reach: compiles wait or are asked for again, no try alone spent (ServiceReach;
    run N3 lost 7,932 compute pipelines that way).
  • Fixes: ad1147cb, 69be3fd1, d450bc17 (tests where two members met), 42cc9868 (main's Linux pressure fixture includes
    private_memory.h).

6. Draw-path emulation on MoltenVK (was #850)

  • Was #677: polygon modes and restart-off strips counted on Apple (mode_census.h; log only).
  • Was #678: a direct draw's 8-bit indices bound with their size (VK_KHR_maintenance5; RX_VK_INDEX8_SIZE).
  • Was #679: count draws rewritten on the GPU without drawIndirectCount, buffer updates copied from the stream (count_draws.h).
  • Was #680: direct draws that read the draw index drawn as one indirect record (drawid_direct.h).
  • Was #691: docs: MoltenVK main 5189f8de with the argbuf-slots patch as the recommended input (docs/macos-moltenvk.md).
  • Was #701: fans keyed apart from the other triangle topologies (fan_key.h; the program cache stamp).
  • Was #702: an indirect fan of more than one record drawn a call a record (fan_indirect.h).
  • Was #703: flat values from each primitive's last vertex, as NVN (provoking.h).
  • Fixes: 8e3cbac6 (test_fan_indirect's cut), 6551f4c5 (draw_index8_report's brace), e0cc1407 (test_fan_key reads main's
    predicted_keys_read(), #713).

7. Indirect quads and mesh count draws on every driver, with their Mac halves (was #851)

  • a10d6c62 (was #705, every driver): indirect quad draws drawn: their records rewritten on the GPU into indexed triangle lists
    (gpu/vk/quad_draws.h, quad_draws.comp, quad_rewrite in vk_draw.cpp).
  • fbaba871 (was #707, every GPU on the mesh compute fallback): mesh count draws drawn, the records area grown past 64 MB when
    the allowance holds it, the cuts counted (mesh_area.h, count_draws.h, host/nvn_native.c).
  • Was #706: quads provoke the same corners where the first vertex provokes (Apple).
  • Was #708: the fallback's rotation follows the count draws and the grown area (Apple).
  • Fixes: a39f027d (#705 with area 6's censuses and checks), af4f2999 (test_drawid_direct pins #707's DrawIndex condition).

8. Mac performance (was #852)

  • Was #704: frame cost lines, a GPU timeline and the bench's A/B arm, every platform, off by default (vk_perf.cpp, perf_lines.h).
  • Was #780: LoadClear; dropped again by 506752c2 (measured under the noise).
  • Was #782: restart-off 8-bit draws fetch vertex 255 as NVN does (RX_VK_INDEX8_RAW); its look-ahead dropped by 95aa6b91
    (measured under the noise).
  • Was #783: the mesh fallback's draws of a pass batched in one pass (mesh_batch.h; RX_VK_MESH_BATCH).
  • Ports: ebf9d527, 615e698e (no provoking-vertex draw left out in a mesh batch; the every-platform middle commit is #853),
    f9b1c81b (macOS's write-mark walk, 64 marks a test in 16-byte loads; collect_in in host/rx_backend.c, HOS_COLLECT_VECTOR).
  • Fixes: df8c1602, 18bf99b2, 325a9147, 7c0a8884 (tests where two members met), b0326575 (the perf-lines and
    stream-room tests read main's split_part and FlatMap, #443, #231).

The join: 8d337c08 merges area 5 into areas 6-8's line (Reviewer notes); 6343f29e names #707's new fallback bind under
RX_VK_LMEM_LOG, as #681 names the other fallback binds (log only; found by test_private_memory at the join).

Docs: docs/development.md (the macOS build and every switch's row), docs/control.md, docs/pipeline-cache-storage.md,
docs/macos-moltenvk.md, gpu/vk/VULKAN.md.

Measurements

Verdict: works. Main cannot build on a Mac; with this PR's commits (integration builds) the game held 1,197 s in play on
arm64 and 18 m 22 s under Rosetta from the field-dawn save, every draw drawn, all eight heavy compiles made, no device loss, a
clean exit. Two changes measured faster on the same build and ship on: MeshBatch (−1.0 ms a frame) and macOS's vector walk (the
replay's memory sync 3.25 → 0.25 ms a frame); two measured under the noise and are dropped (LoadClear, Widen8's look-ahead).

Hardware: macOS 26.7.1 (25G241), Apple M4 Max (40-core GPU), 16-core CPU, 64 GB; MoltenVK main 5189f8de + argbuf-slots (arm64 c170a745; its x86_64 slice 96313ca8 under Rosetta)
Scene: Hyrule Field from the field-dawn save (slot 00, START then A), windowless unless named, LS's defaults; frame cap 60 for I39's E-series (E7: 240, which never binds), HOS_FPS_MAX=240 for E9
Method: each run's longshot_log.txt (the precompile, hand-off, compile and close lines; the FPS counter's Dev level; RX_VK_PERF_LINES' L1-L6), medians over the hold's 120-present periods from +20 s; one start each (E7 against E2 measured the run-to-run noise: 0.17 ms of frame)
How to reproduce: tools/ls-run.py (the port's runner) on a macOS build of these commits, the field-dawn save, START and A at the title; the switches in each column

Baseline: main @ 7bacf846 does not build or start on macOS, so the after columns are the port's integration builds I41
78ec1c47 and I42 63fc3d2c (I41 plus slow-first), which carry these commits as they were before the rebase onto 7bacf846
(without 30252cf5 and the Sweep4 test fixes; with the every-platform #788 and #853, which are separate PRs). The A/Bs below
compare one build with a switch off and on. No game run at this PR's head yet (Testing).

Before: main @ 7bacf846 After, arm64 (E9a): integration @ 78ec1c47 After, x86_64 under Rosetta (R39): integration @ 63fc3d2c
builds and packages on macOS no: the builder takes the Linux route yes yes
start to the title and play no hand-off 8 m 14 s after the start, play 48 s later hand-off 9 m 42 s, play at 10 m 48 s
held in play - 1,197 s 18 m 22 s (a 1,093 s hold)
skipped draws / provoking-vertex draws left out, in the hold - 0 / 0 0 in 214 hold groups / 0
heavy compiles (4 giant mesh programs, 4 others) - 8 of 8 made, 0 XPC errors 8 of 8 made, 0 XPC errors, 0 [mvk-error]
44511d69 (the field's tree leaves) - made 895.6 s into its compile first in the precompile, made 1,115.8 s after the start
device loss, exit - none; exit 0, clean end, 0 crash reports none (0 IOGPU/AGX lines); clean exit
the runs' checks - 12 of 12 must-shows 15 of 15 must-shows, 18 of 18 RosettaImport checks
frame rate in the hold - 37.1 fps, 26.95 ms, GPU 19.4 ms 23.5 fps under load 14.7, GPU 20.2 ms
E9a (mac-arm64-78ec1c47-01): precompile 479.0 s, hand-off 07:23:28.6, play 07:24:16, hold 07:24:25.3-07:44:22.6; 12 of 12 checks true
giants: 5096bcc7 50.2 s, 6dbfda5a 29.9, 5c945415 34.1, 55d1da3f 34.1; 44511d69 895.6 s; 0 XPC errors; 0 "not made"; skips 0 in the hold
R39 (mac-x86-63fc3d2c-01): 47798 program keys kept; hand-off L32179 "41877 of 42137 done"; play-hold 656.9-1,750.4 s; 25,565 frames in 1,090.0 s
#38 (mac-arm64-63fc3d2c-01, windowed 1280x752): 148 hold groups all "0 skipped"; 32.79 frames/s over 540 s; 44511d69 made 986.1 s after the start

The windowed run #38 (I42) held 540 s, 0 skipped draws, the tree leafy from its shot after 44511d69 was made; its lane's death
cut the hold at 542 s (the game quit on request, exit 0). The owner looked at E9a's shots in Preview.

The speed-ups (same build, switch off against on, one 600 s hold each):

field-dawn hold Before (switch off) After (as it ships)
MeshBatch, I39 7a7726fe, E4 → E2: fps / frame ms / GPU ms 32.6 / 30.67 / 20.2 33.7 / 29.67 / 19.1
MeshBatch: pass ends a frame / MB loaded and stored a frame 188.0 / 649 133.9 / 378
vector walk, I41 78ec1c47, E9b (HOS_COLLECT_VECTOR=0) → E9c: the replay's memory sync, ms a frame 3.25 0.25
vector walk: frame − GPU ms / a capture's scan, ms a submit 10.74 / 0.190 7.58 / 0.020
vector walk: frame ms (fps) 33.56 (29.8) 27.10 (36.9); about half is GPU time the walk is not shown to cause: about 3.1 ms at equal GPU time
LoadClear (E4c → E2), Widen8's look-ahead (E4b → E2): frame ms 29.67 each 29.67: under the noise, both dropped
MeshBatch, LoadClear and Widen8's look-ahead together, E3 → E2 (what ships is E2 within the noise; uncapped, E7: 33.9 fps) 32.3 fps, 30.96 ms 33.7 fps, 29.67 ms

Across builds, not A/Bs: MoltenVK 1.4.2 → main 5189f8de + argbuf-slots, GPU 23.1 → 20.25 ms a frame (#691's starts); with
RX_VK_INDEX8_RAW, MoltenVK's 8-bit pass splits 57.5 → 0 a frame (I38 → I39). MoltenVK's asynchronous submits measured 0.63
ms slower (E6): not adopted. The every-platform present-nowait (#656) measured no gain on this Mac (E10).

What each area fixed, as each original PR measured it (its build or GPU probe named; history):

area (was) Before After
2 unified budget (#642): the GPU allowance 53,084 MB, the driver's (run #22 lost the device) 10.2-20.8 GB, read from the system (runs #24, #26)
2, 5 Metal's cache folder (#653, #786) denied cache opens about 1.5 a compile; windowed start to hand-off 24 m 28 s (#35) 0; 6 m 53 s (#36)
2 drivers (#654): the start's preparation - MoltenVK 38,809 programs in 58.0 s; KosmicKrisp 1,607 in 1,770 s, no title: MoltenVK stays the default
3 descriptor limits (#643-#646): pipelines lost at the first start 256 (alias errors) 0, arm64 and Rosetta
4 back end (#696; #697): pipeline creation (GL-01; LM-01/02) 15.36 s; 7,518 ms at 64 KiB local memory 1.45 s; 15-16 ms
4 back end (#693; #694): Metal's refusals (CG-01; SG-01) refused past 256 braces; 14 vertex pipelines refused made, exact words; 19 of 19
4 Rosetta imports (#686) about 1,640 draws a frame left out (refused imports) 0 refused imports (runs #33, #34)
5 preparation (#650; #664) 39 programs in 180 s; 1,550.4 s compiling 1,381 compute pipelines 230; 118.3 s with none
5 thread stacks (#651) SIGILL in SPIRV-Cross at about 93 s (start #6) starts #7-#9 clean
5 precompile (#652; #665) no title (run #12); first frame 188-198 s after the hand-off title (run #17); 5.0 s
5 slow-first (port): 44511d69 made, from the start 1,439.9 s (E9a) 986.1 s (#38)
6 8-bit indices (#678): GPU memory loading the first scene 53.1 GB, out of memory, device lost 9.3 GB in play
6 draw index; fans; flat values (#680; #701; #703), MoltenVK probes 1,688 of 3,744 stale; 96 of 288 wrong; the first vertex's 0; 0; the last vertex's (NVN's), every pixel
7 indirect quads; mesh count draws (#705; #707), every driver left out drawn: equal to the direct path's quads (QD-01, 41 of 41) and to each record drawn alone (MC-01, 29 of 29)
8 provoking-vertex draws in batched passes (stream-room port) 0.6-0.9 left out a frame (run #36) 0 (E9a)

Flags and settings

The switches and build inputs, in area order: new ones read on macOS or MoltenVK/KosmicKrisp only; three measuring
switches (RX_VK_PERF_LINES, RX_VK_GPU_TIMELINE, RX_VK_BENCH_AB) on every platform, off by default; nothing changes off the Mac
with them unset. RX_VK_LOAD_CLEAR and RX_VK_WIDEN8 are gone again (measured under the noise). Main's switches the diff shows,
read as before: RX_VK_DLSS_ACTORS, RX_VK_GPU_DUMP, RX_VK_MESH_IND_COUNT_WORD, RX_VK_NO_UPSCALE_STUB, HOS_HEADLESS,
RX_VK_NO_WARM, RX_VK_PCACHE_FETCH_LOCK, RX_VK_SKIP_PROG, RX_VK_BENCH, RX_VK_CHUNK, RX_VK_DRAW_STATS,
RX_VK_PASS_BARRIER, RX_VK_PASS_TIMING, RX_VK_BARRIER_DEDUPE_OFF, RX_VK_BARRIER_EVERY_DRAW, RX_VK_PUSH_STATE_OLD,
HOS_COLLECT_WIDE.

Flag What it is Before this PR After this PR Effect Helps / doesn't help / untested Recommendation
RX_VK_LIBRARY=<path> macOS: the first Vulkan loader or MoltenVK dylib to try not read unset: the one beside the game the renderer and SDL load it first; a bad path logged, the next tried helps on macOS; untested on an Intel Mac unset
RX_ARCH=arm64 or x86_64 the macOS build's architecture (macOS built as Linux) arm64 on Apple silicon, x86_64 on an Intel Mac the Mach-O target macOS only x86_64 for the Rosetta route
LONGSHOT_MOLTENVK macOS build input: the MoltenVK dylib not read required on macOS packaged as libMoltenVK.dylib recommended: main 5189f8de + argbuf-slots (docs/macos-moltenvk.md; 0 lost pipelines); 1.4.2 accepted the recommended build, once approved
LONGSHOT_SDL3 macOS build input: SDL3 for SDL2-compat not read unset; required when the SDL2 dylib names SDL3 packaged as libSDL3.0.dylib untested: SDL2-compat loading it in a game set beside LONGSHOT_SDL2
LONGSHOT_DARWIN_ARCHIVE_RECEIPT, LONGSHOT_DARWIN_ARCHIVE_RECEIPT_SHA256 the receipt for FFmpeg's NASM members without a minimum-macOS command, and its digest not read unset: such members refused admits exactly the receipted members x86_64 FFmpeg with NASM only set both for that FFmpeg
LONGSHOT_VULKAN_LOADER, LONGSHOT_KOSMICKRISP macOS build inputs: LunarG's loader; KosmicKrisp (arm64) not read optional, unset the package carries the loader and a manifest per driver lets one package measure both drivers for measurement packages
RX_MARCH, EMSDK, SDKROOT, LONGSHOT_FFMPEG, LONGSHOT_SDL2, RX_VK_ONLY (existing) CPU level, LLVM prefix, Apple's SDK, FFmpeg, SDL2, a renderer-only build read on a Mac as on Linux Mac defaults (arm64: no x86 level; x86_64: x86-64-v2); SDL2 packaged the macOS build works Windows and Linux unchanged the Mac defaults
LONGSHOT_NGX_SDK, LONGSHOT_FSR (existing) NVIDIA NGX's SDK, AMD's FSR runtime read on a Mac as on Linux macOS: the build stops, "no macOS build" no NGX or FSR on a Mac neither has a macOS library unset on a Mac
HOS_PROFILE, HOS_THREAD_TIMES, HOS_SAMPLE, HOS_SAMPLE_ALL, HOS_SAMPLE_FILE, HOS_CHAIN, RX_MAPS (existing) the host profiler, sampler and maps no macOS route on macOS as on Linux profiling on a Mac untested in a game run profiling only
HOS_WATCH, HOS_PIN_BY_CORE, HOS_PIN, HOS_RESERVE_CORE (existing) watchpoints, pinning, the reserved core no macOS route on macOS each says once it is unavailable none on macOS by design unset on macOS
HOS_ZERO_ALL_PAGES, HOS_KEEP_FREED_PAGES, RX_NVN_WATCH_TEXELS_SRC, RX_NVN_WATCH_AFTER, RX_NVN_WATCH_ALL (existing) guest-memory and write-watch debugging 4 KiB-page assumptions on macOS 16 KiB host pages, main's meaning debugging works on a Mac Windows and Linux unchanged debugging only
RX_VK_UNIFIED_BUDGET=0 the GPU allowance the driver's again (the driver's) on, on a Mac's unified memory budgets follow what the Mac has free; vk: unified memory line helps: memory pressure; untested: 8-32 GB Macs on; =0 only to compare
RX_VK_METAL_CACHE_DIR=<folder> Metal's shader cache folder Metal's own under /var/folders unset: unchanged sandboxed or carried starts find a warm cache helps: sandboxed runs (#36); no effect on a normal start off; set for sandboxed runs
RX_VK_DRIVER macOS: kosmickrisp or moltenvk on a loader package (no switch) unset: MoltenVK the driver the loader is given kosmickrisp: measurement only (run #20, no title) unset
RX_VK_SET_FOR_TABLES, RX_VK_SET_FOR_LENGTHS 0 or 1: ordinary sets for the programs a push breaks on MoltenVK (pushed) unset: on with MoltenVK only those pipelines made, lengths exact; a close line counts the moves helps: MoltenVK (256 lost → 0); untested: the sets' cost unset
RX_VK_TEXEL_CODECS 0 or 1: texel buffers through carrier codecs (native views) unset: on on macOS when a format query fails those programs translated with codecs helps: macOS; untested =1 elsewhere unset
RX_VK_SPV_PROFILE, RX_VK_SPV_PROFILE_MIN a line per big module, from that many SPIR-V words (no switch) off; 100000 log lines; translation slower diagnosis off
RX_VK_GM_LOOP (existing) storage buffer tables searched in a loop Intel's Mesa driver only also MoltenVK and KosmicKrisp smaller Metal source helps: GL-01 (15.36 → 1.45 s) unset
RX_VK_LOCAL_ZERO_LOOP=0 local memory zeroed by its initializer again (the initializer) the loop on MoltenVK smaller Metal source helps: LM-02; no effect elsewhere unset
RX_VK_COMPILER_SERVICE 0 or 1: the compiler-service preparation and precompile (no switch) on for MoltenVK and KosmicKrisp area 5's order, bounds, hand-off and retries helps: MoltenVK (runs #17-#38, E9a) as it ships; =0 to compare
RX_VK_WORKER_CACHES a pipeline cache per preparation worker (no switch) on for MoltenVK compiles side by side helps: 4.4-4.6× pipelines a second as it ships
RX_VK_PCACHE_LOAD (existing default) the pipeline cache file read and saved read and saved everywhere MoltenVK: neither; elsewhere as before a later MoltenVK start compiles anew helps: 1.41 s against 6.65 s as it ships
RX_VK_SLOW_COMPILE_S, RX_VK_PRECOMPILE_STALL_S (the second existing) slow-compile seconds; nothing finished before the game starts (none); 30 once all handed out 10; 30 whatever is left slow compiles named; the title not held by giants helps: MoltenVK as it ships
RX_VK_GIANT_COMPILES, RX_VK_GIANT_WORDS giants in flight; words that make a giant (no switch) 4; 100000 small items finish beside giants helps: runs #18, #19 as it ships
RX_VK_GIANT_HOLD_PRESENTS, RX_VK_GIANT_HOLD_S, RX_VK_GIANT_ROOM_MB giants held after the hand-off; the longest hold; memory one giant gets (no switch) 1; 120; a quarter of memory, 16384 at most the first frame comes first; giants wait for memory helps: starts 21-24; the room gate untested in a game as it ships
RX_VK_COMPILE_QOS QoS class of giants and work behind the game (no switch) utility Metal serves the game's compiles first untested against default in the game as it ships
RX_VK_ALONE_TRIES, RX_VK_SKIP_LOG tries alone per program; each dispatch left out named (no switch) 2; off a compile failed beside a giant is made, not lost untested in a game (no such failure) as it ships
RX_VK_HEAVY_WEIGHT, RX_VK_HEAVY_WORDS, RX_VK_STALE_COMPILE_S what makes a compile heavy (runs alone); when a compile in flight stops holding them (no switch) 10000000; 1000000; 240 s the four giant mesh programs made helps: GC-02, E9a (all eight made) as it ships
RX_VK_SLOW_FIRST_S an earlier run's compile time from which it goes first (no switch) 240 44511d69 begins with the precompile helps: #38 (986.1 against 1,439.9 s), R39 as it ships
RX_VK_SERVICE_BURST, RX_VK_SERVICE_FAST_MS failures in a row, each this fast, that mean Metal's compiler service is out of reach (no switch) 8; 250 ms compiles wait or are asked again, no try alone spent untested in a game (run N3's case, game-free) as it ships
RX_VK_METAL_ARCHIVE_DIR macOS: MoltenVK's pipelines in Metal binary archives (no switch) unset: off a start makes earlier starts' pipelines without compiling helps: ARC-2 (24,251 from archives); doesn't: +29 GB footprint off
RX_VK_LMEM_LOG, RX_VK_LMEM_LOG_MIN macOS: each module's private memory logged, from that many bytes a thread (no switch) off; 1024 log lines diagnosis off
RX_VK_INDEX8_SIZE 0 or 1: a direct draw's 8-bit indices bound with their size (bound to the pool's end) on for MoltenVK only MoltenVK widens only the draw's indices helps: 53.1 → 9.3 GB (runs #23, #24) as it ships
RX_VK_COUNT_REWRITE=1 the count-draw rewrite where the device has drawIndirectCount too (macOS) (no switch) off: the rewrite only without the feature compares the rewrite with the driver's untested in a game off; for testing
RX_VK_PERF_LINES=1, RX_VK_GPU_TIMELINE=1 or 2, RX_VK_BENCH_AB=<arm> every platform: frame cost lines; the GPU timeline; the bench's B arm (no switch) off log lines; relaxed counters helps: measuring (the E-series) off; for diagnosis
RX_VK_INDEX8_RAW 0 or 1: restart-off 8-bit draws fetch 0xFF as vertex 255 (MoltenVK's 0xFFFF: primitives lost) on for MoltenVK only NVN's primitives helps: W8-01 r2 (14 of 14) as it ships
RX_VK_MESH_BATCH 0 or <n>: the mesh fallback's draws of a pass batched (each breaks its pass) on for MoltenVK, 8 members 54 fewer pass ends a frame helps: −1.0 ms frame (E4 → E2) as it ships
HOS_COLLECT_VECTOR=0 macOS: the write-mark walk a byte load each, as before (no switch) the vector walk the same pages, order and marks helps: −3.0 ms memory sync (E9b → E9c) as it ships; =0 for A/B

Testing

Current revision validation (594d5296)

Tested: game-free validation of the 594d5296 source on this Mac, as detailed below; no current-revision game or Windows/Linux run is claimed.

  • The working-source snapshot was verified against the committed tree. The main merge resolves descriptor-array atomics, compute-pipeline publication, segmented writes/import lifetimes, Darwin link/package handling and updated fixtures; no archive or NETWORK_KEEP default was enabled.
  • The full source run before fixture repairs was 670 passed, 31 failed, 17 skipped, against matching main a8a30c22 at 584/43/18. Six merge-related fixture failures were repaired and all six passed focused reruns. A Windows-only execution test gained its explicit macOS skip; the ordinary runner excludes it and still includes the passing portable report test. No new full-suite total is claimed after those fixture-only edits.
  • 20 whole-file compiles passed, covering the changed runtime translation units on arm64 and x86_64. Runtime/build/header sources stayed unchanged during the subsequent fixture repairs.
  • 36 synthetic image-array SPIR-V modules validated. Renderer linkage passed 1,218 name/architecture checks, with all 631 cross-file symbols per architecture resolved. Existing compiler extension warnings were retained, not represented as a warning-free build.
  • No game run or Windows/Linux execution has yet qualified this revision. The game-run and broader earlier-compilation evidence below belongs to its stated earlier commits.

Earlier validation (6343f29e)

Earlier tested revision: macOS 26.7.1, Apple M4 Max, 16-core CPU, 64 GB, Apple clang 21.0.0, at 6343f29e on main 7bacf846,
arm64 and x86_64 under Rosetta; these results are historical, not a fresh run of 594d5296:

  • The full game-free suite (python -I -B tests/run_all.py through tools/ls-suite.py), compared by test name with main
    7bacf846's on this Mac: 649 passed, 16 failed, 17 skipped, against 558/34/17. New and passing: the 73 new tests. Fixed
    (FAIL on main): 17, the host's macOS repairs (test_collect_wide, test_control, test_crash_record, test_longshot_ctl,
    test_low_memory_notice, test_prof_symbols, test_mem_gate, test_mem_gate_children, test_mirror_trim,
    test_oot_state_tap, test_report_run and six cache checks). test_appimage_package_retry is skipped on macOS by #454's
    declaration, and test_dav1d_av1 runs and passes (#454 links dav1d). Nothing that passes on main fails. The 16 failures fail
    on main too, on this Mac: test_appimage_player_build, test_crash_dialog, test_env_on, test_game_layout,
    test_lift_cleanup_error, test_linux_preflight, test_make_game_cache, test_missing_nup, test_options_budget_once,
    test_options_path, test_pipeline_tour, test_readback_late, test_split_giants, test_vk_occlusion_queries,
    test_vk_pgo, test_walk_key.
  • The original PRs' own tests and the tests each area's range touches: 482 jobs (222 arm64, 194 x86_64, 20 both in one run, 46
    without an architecture), 459 pass. The 23 others are explained, none a defect of this head: 16 base-tree checks of area 4
    (test_seg_shader --base-tree against seven old member bases, test_local_zero --base) differ from those bases only in the
    mesh fallback's modules, which #707 (area 7) changes on purpose (they pass up to area 6); the consumer-check job, 54 of its 60
    cases as required; 4 runs of main's own failing test_vk_occlusion_queries; 2 of #667's old test_metal_cache_dir --headers
    form (#786's form passes). 33 jobs passed on a second run: Rosetta SIGKILLs under load (exit -9, no crash report), and runs
    repeated after a fix.
  • Open note, area 4's consumer checks: the seg-bind positives (both arches) report "common path differs from B2's cut"
    because they compare with B2 918e6214, from before main 7bacf846 changed the functions they cut (the same at area 4's own
    tip); the seg-gathers and seg-xfer positives cannot build B2 with today's fixtures, which include areas 6 and 8's headers
    (they pass at area 4's tip). test_seg_bind, test_seg_gathers and test_seg_xfer themselves pass at this head, both arches.
  • Whole-file compiles of the 59 non-test C/C++ files this head changes: 46 with the tree's own nx2/build.py macOS commands
    (104 compiles, arm64 and x86_64) and the 12 gpu/vk/eden back-end files with the renderer library's flags (24 compiles): 128
    compiles, all exit 0; nx2/bake_ds/bake_ds.cpp (a Linux lift tool) through its member test.
  • The renderer's link check (each defining gpu/vk file compiled with the tree's renderer_flags(), arm64 and x86_64): 68 of
    68 objects, 610 cross-file mkwvk:: symbols per architecture, every one defined.
  • Off Apple (unifdef -U__APPLE__ of the 130 changed non-test C/C++ files against main, compared as tokens): 16 the same, 55
    differ, 59 new (11 of them only Apple blocks). Each area's off-Apple change, compared at its tip with its original PRs' before
    the rebase, is that change or differs by the rebase's hand resolutions only (Reviewer notes); the join adds nothing off Apple
    but 6343f29e's log-only line. What differs is listed under Risks.
  • Each area at its own tip, before the join: compiles and link checks all exit 0; suites at the rebased tips 587/16/17,
    589/18/17, 559/35/17, 614/20/17, 627/20/17, 621/21/17, 626/22/17, 629/23/17 (areas 1-8), whose new failures led to the
    seven fixture fixes named above (beside the load-sensitive test_gpu_hang_watch).
  • In the game (integration builds, before the rebase; Measurements): E9a on I41 (arm64, 1,197 s), R39 on I42 (Rosetta, 18 m 22
    s) and #38 on I42 (windowed, 540 s); earlier, #32 on I38 (arm64, 900 s) and #34 on I38 (Rosetta, 16 m 52 s).

Not tested: Windows and Linux execution of the current revision; a game run of 594d5296. The game runs below are earlier
integration builds without 30252cf5. No scene with an indirect quad draw or a mesh count draw (field-dawn draws neither:
E9a has no vk: quad draws line and vk: mesh draws 0.0 a frame with a count), so area 7's every-driver paths ran only in the
tests and the QD-01 and MC-01 probes, never on a GPU with mesh shaders or another driver's fallback. A segmented domain in a
game; KosmicKrisp in a game beyond run #20; a warm start from Metal binary archives as shipped (off); a Rosetta frame rate in a
quiet hold on I42; Macs with 8-32 GB; macOS 14.4 and 15 (every run was on 26.7.1); an Intel Mac; SDL2-compat loading the
packaged SDL3 in a game.

Must be tested:

  • Windows and Linux, any GPU: build this PR (head 594d5296) and main a8a30c22 the same way, run python -I -B tests/run_all.py
    on each and start each to the title, expecting successful builds and no regression against that main, with every unsupported
    check explicitly declared (by hand: compare the suite results and renderer/cache startup logs). T-3F2Q was opened for the
    earlier 6343f29e; it is not acceptance evidence for this updated head. Current-head qualification is required before ready.
  • Windows and Linux, a GPU on the mesh compute fallback and one with mesh shaders: (fallback GPUs: GTX 10xx, RX 5000, AMD on
    Linux by default, Navi 21/22 on Windows) play to the field with RX_VK_VALIDATION=1, expecting vk: quad draws (…) with 0
    left out once a quad is drawn, vk: mesh draws (…) with none left out, vk: mesh fallback cuts so far all zero on the
    fallback GPU, no validation error, no vk: provoking vertex line and the scenes as on main (by hand: T-3F2Q, with
    screenshots of anything that differs)
  • Windows and Linux, any GPU: start this PR once more with RX_VK_PERF_LINES=1 RX_VK_GPU_TIMELINE=1 and play a minute,
    expecting the vk: L1-L6 lines and a T1 line every 120 presents, the frame times as without them (by hand: T-3F2Q)

Risks

What could break: on Windows and Linux, by intent: every driver now draws indirect quad draws and every GPU on the mesh
compute fallback draws mesh count draws, both left out before (a pass break per indirect quad draw, device-wide buffers made at
the first one; the fallback's records area can grow past 64 MB; fallback stages that load DrawID read it pushed); a startup that
fails part-way unwinds what it made; on Linux, Discord presence's socket code and the thread-creation error paths; the build's
Windows and Linux arrays moved into functions (pinned element for element). Compiled everywhere but gated off at run time: the
back end's new emit paths, the descriptor-set choice, the compiler-service precompile, the draw-path fixes, MeshBatch; a gate
held wrong would change modules or commands off the Mac (the fixtures check the modules byte for byte against main's). The perf
hooks cost one flag load each with their switches off (about 1 ns a call). On macOS everything is new and has run game-free and
in the integration builds only: the start's order under the compiler service; sets instead of pushes, null-descriptor guards,
stored image reads and one-lane warps cost what no frame has measured.

Turning it off: the macOS code is behind __APPLE__ or a driver gate; the switches above turn its parts off
(RX_VK_COMPILER_SERVICE=0, RX_VK_MESH_BATCH=0, RX_VK_UNIFIED_BUDGET=0, RX_VK_SET_FOR_TABLES=0, …). The every-driver
draws of area 7 have no switch: revert their two commits (was #705, #707), or the PR.

Compatibility: every platform lifts the game again once (nx2/kit.py and the new nx2/darwin_toolchain.py are lift
sources), prepares its shaders again once (the translator's stamp changes: vk_shader.cpp, the back end, the fallback's DrawID),
rebuilds its program cache once (kProgramCacheFormat 1 → 3) and compiles the host's objects again once. The vk ABI:
MKWVK_API_VERSION is 27 on macOS only (host slots appended by #438, #491, #686 and #786; the macOS executable and renderer are
built together); Windows and Linux keep main's 23 with the same structure. Saves and longshot_options.ini are unchanged. Every
platform's log gains fields: the vk: vendor fixes line (0 off MoltenVK), the quad and mesh draw reports. On MoltenVK the
pipeline cache file is no longer read or written, and longshot_pipelines.bin.slow lists slow compiles.

Reviewer notes

Reading order: the areas in commit order. The every-platform parts to read closely: area 7's two commits (was #705, #707),
#491's startup rollback (area 2), #490's Linux changes (area 1) and #704's measuring hooks (area 8). Then the Mac's: the build
scripts and host/posix/darwin_*.c (1), vk_memory.cpp's imports and the budget (2), layout_pushes() (3), the back end by
Profile flag (4), precompile_handoff.h (5), draw() in vk_draw.cpp (6, 7, 8).

By commit: git log --reverse --no-merges --format='%h %s' 7bacf846..6343f29e. Each original PR's commit names it (Was: #NNN
with its branch; area 7's two say "#705 restacked …", "#707 …"); that PR's page keeps its review and measurements. The named
fix commits sit after their area's members. The maintainers squash at merge.

Topology: each topic's commits are linear on its base; the merges are the stack's own.

7bacf846 ── #845 ── #846 ── #848 ──┬── #849 ─────────────────────┐
                             │  │  └── #850 ── #851 ── #852 ─────┴── 8d337c08 ── 6343f29e
7bacf846 ── #847 ────────────┘  │
7bacf846 ── #431 (its own PR) ──┘

#848 sits on #846 and merges #847 and #431; seven "Merge topic/ into topic/" commits carry Sweep4's test fixes up
the stack. #849 and #850 both sit on #848, so one merge commit, 8d337c08, joins #849's line to #850-#852's: in its five
conflicted files (vk_draw.cpp, vk_main.cpp, vk_progcache.cpp, vk_replay.cpp, vk_vendor.h) both sides add at one
place, and the merge keeps both, in integration build I42's (63fc3d2c) order. Two more merges (562d10b3, e9404d81) take
areas 4 and 5's last fixture fixes up, and 6343f29e adds the one line where areas 5 and 7 meet.

Rebased onto main 7bacf846 (from aa95d35f); the hand resolutions, each also in its commit's message:

  • d85dac1a (#453), 0e7ee58e (#479): main dropped the WebGPU renderer (#577), so the macOS build has none; main's host-source
    line stays verbatim (main's test_no_webgpu.py unchanged), and the link takes resources=exe_resources() (#857).
  • 81c21324 (#491): main's evicted_import_bytes accounting (#223) kept before destroy_import(p); ec5731cc (#642): main's
    Linux pressure kept beside the unified-memory keep_now.
  • #847: rebased by HumanBean on the forge (88e914ad); vk_shader.h keeps main's record_at/record_size and array_length.
  • a9888f20 (#663): main's FlatMap c1_at (#231) with the segment arena; by the owner's decision on #403, main's generic dummies
    stay on every device without nullDescriptor (make_dummies and its test unchanged) and the typed stand-ins move to
    make_stand_ins(), Apple only. #431's merge takes its earlier resolution (vk_memory.cpp and two tests).
  • 64c14f29 (#651), 9ab883a4 (#665): include lines only.
  • #851 is linear now: #705 and #707 are one commit each at its base; the brace fix that once followed them is not needed.
  • 256ddf7e (#704): the perf op before main's split_part (#443), its reason line inside it; e26f6c09 (#783): main's
    c1_at.reset() before the mesh batch's start (test_mesh_batch asks for it, the owner's decision); 14cc564d, 644770fc,
    506752c2: the LoadClear and Widen8 lines around main's split.

Main integration: 594d5296 has parents 6343f29e and a8a30c22; the previously listed 19 conflicts with that main are
resolved. Current-revision validation is listed above. Any newer upstream changes and the live mergeability state must be
checked again before this PR is marked ready; no additional rebase or acceptance run is scheduled during the owner's hold.

Related every-platform PRs, kept separate: #431 (merged inside #848; review it there; its two commits drop out of this diff
once it lands); #853 (a direct quad draw's triangles grow the stream under RX_VK_STREAM_GROW_OFF: the every-platform half of
area 8's stream-room port; merges cleanly with this PR); #907 (a direct non-indexed quad draw's BaseVertex is its first vertex,
as area 7's indirect quads read it; conflicts with this PR in vk_draw.cpp); #936 (the write-mark walk vectorised on every
platform, of which area 8's macOS walk is the Mac form; conflicts in host/rx_backend.c, tests/test_collect_wide.py and
docs/development.md: whichever lands second takes the other's walk); #788 (async-safe frees; area 4 carries its Mac-only part;
merges cleanly); #656 (present-nowait; no gain on this Mac). Independent of this PR: #423 #428 #434 #451 #452 #474 #475 #498 #670
#700 #912. These overlap notes were assessed at 6343f29e; recheck them before integrating another PR.

Coming separately: the macOS nightly builder (a zip for Apple silicon and CircleCI jobs), as its own PR on top of this one.

Issues

See #420.

Checklist

Everyone

  • One topic.
  • The title is a Conventional Commit (type(scope): description) of the status line's type.
  • Why gives the reason plainly and links the issues that fit (the tracker searched).
  • Measurements has a verdict, or one line saying why there is nothing to measure.
  • Testing names what was tested, what wasn't, and what must still be tested, where and how. (Test request T-3F2Q.)
  • Rebased on current main: main a8a30c22 is merged at 594d5296; a final live-main check is owed before ready.
  • python -I -B tests/run_all.py passes (any failure that also fails on main is named). See current-revision full-run and focused-repair evidence under Testing; Windows/Linux and final game-build acceptance remain open.
  • No game files, dumps, build output or generated files.
  • third_party/ untouched (a new folder with a PROVENANCE.md instead).
  • The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled.

When it applies

  • AI assistance recorded with Assisted-by: / Co-Authored-By: trailers.
  • Numbers from the same PC, scene and settings, at least 2 interleaved runs each, the median reported. (Same PC, scene and settings and the hold's median, but one start each: E7 against E2 measured the run-to-run noise.)
  • Switches documented (docs/development.md; the README for a menu row) and shipped at their recommended value.
  • MKWVK_API_VERSION bumped (gpu/vk/vk_api.h's MkwVkHost or MkwVkRenderer changed). (macOS 27; Windows and Linux 23.)
  • The SPIR-V headers regenerated with glslang (a shader changed).
  • A game-free test added for the fix, failing on main and passing here.
  • A check under tests/ that reads changed source updated in this PR, not weakened.
  • Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. (Not built there yet: the test request.)
  • Docs updated.
**Type:** feat · **Risk:** medium · **Tested on:** macOS 26.7.1, Apple M4 Max (arm64; x86_64 under Rosetta) · **Needs:** Windows and Linux, any GPU (and one GPU on the mesh compute fallback) **Current revision:** `594d5296` merges main `a8a30c22` into the combined macOS head `6343f29e`. The PR remains WIP: final game-build acceptance, Windows/Linux qualification and guide/UI review are still open. Work is paused after this push at the owner's request. ## Why Nobody can build or run LS on a Mac today. The builder takes the Linux route there, the host's POSIX layer is written for Linux and x86, and the Vulkan renderer neither finds a driver on macOS nor works within what MoltenVK and Metal allow: shaders Metal refuses, descriptor sets MoltenVK cannot push, a compiler service that dies under the game's giant programs, draws MoltenVK draws differently or not at all, and a GPU budget that ran a 64 GB Mac out of memory. This PR is the macOS port: LS builds on a Mac (natively on Apple silicon, and as x86_64 under Rosetta), packages a game folder for macOS 14.4 and later, and plays on Metal through MoltenVK (KosmicKrisp opt-in), held in play for over 15 minutes on both routes. Two kinds of draw the Mac work found missing on every driver are drawn here for everyone: indirect quad draws, and mesh count draws on GPUs that use LS's mesh compute fallback. It replaces the macOS topic PRs #845-#852 (71 earlier PRs in all) with one PR; the commits stay one per original change. See #420. ## What changed The build scripts get a Mach-O route and a packager; the host gets native Darwin memory, waits, faults, threads, control and crash records; the renderer loads MoltenVK (or KosmicKrisp through LunarG's loader), budgets from unified memory, and works around what MoltenVK and Metal lack, area by area below. Almost everything is behind `__APPLE__` or a run-time gate on the driver (`dev.driver_id`, vendor fixes, `Profile` flags); what changes on Windows and Linux is listed under Risks. The original `6343f29e` series below contains 104 non-merge commits and 12 merges; `594d5296` additionally integrates main's newer renderer, host, build and shared-tooling changes while preserving the Mac platform gates. ### 1. macOS host (was #845) - Was #454: the game-free runner knows macOS (`tests/run_all.py`: `macos`, its skip reasons and timing). - Was #477: arm64 host jumps and pause hints (`host/posix/darwin_cpu.c`). - Was #478: guest pages on macOS (`host/posix/darwin_mem.c`: a Mach reservation, exact zeroing, 4 KiB guest rules on 16 KiB pages). - Was #436: Darwin fault contexts on both CPU routes (`darwin_fault.c`, for `win32_posix.c`'s fault bridge). - Was #437: waits and deadlines, one sequence word shared by the executable and the renderer (`darwin_wait.c`, `darwin_wait_state.c`). - Was #438: the Vulkan loader and device admission (`gpu/vk/vk_loader.h`, `vk_main.cpp`, `host/posix/darwin_vulkan.c`; `RX_VK_LIBRARY`). - Was #490: Mach threads, guarded fibers, restart and `posix_spawn`, memory counters, a Mach sampling profiler; on Linux, Discord IPC (`host/discord_rpc.c`) and the thread error paths (`win32_posix.c`) hardened. - Was #453: Mach-O build commands (`nx2/darwin_toolchain.py`, `nx2/darwin_build.py`; `RX_ARCH`); Windows' and Linux' arrays move into four functions unchanged, element for element (`tests/build_flags_main.json`). - Was #479: each Darwin helper classified, every library checked, the game folder carries relocated, signed copies (`nx2/darwin_package.py`, `nx2/darwin_archive.py`). - Was #455: the builder's memory gate on macOS (`nx2/darwin_memory.py`). - Was #456, #457: control bridge sockets (`host/posix/darwin_control_sockets.c`), and the control test's quit case. - Was #476: cache file reservations (`F_PREALLOCATE` in `pipeline_cache_file.h`, `F_RDADVISE` in `vk_progcache.cpp`). - Was #480: guest memory ownership on 16 KiB pages (`darwin_guest_mem.c`). - Was #492: `vk_programs.cpp`, `vk_shader.cpp` and the debug tools build on Darwin. - Was #511: crash records (`hos_report_run.c`, `hos_crash_record.c`). - Was #516: `longshot_ctl` sessions (`scripts/longshot_ctl.py`). ### 2. Vulkan on Metal (was #846) - Was #491: host imports pinned until their last Vulkan owner (`gpu/vk/darwin_import.h`, `vk_memory.cpp`); every platform: a startup that fails part-way unwinds (`replay_start_rollback()`, `vma_startup_rollback()`), `vmaDestroyAllocator` is a recorder drain boundary, import pools are moved, not copied; on Linux `MessageBoxA` and `waveOutOpen` checks. - Was #642: the unified-memory budget (`gpu/vk/unified_budget.h`, `system_memory.h`, `vram_usage()`; `RX_VK_UNIFIED_BUDGET`). - Was #653: Metal's shader cache folder (`gpu/vk/metal_cache.h`; `RX_VK_METAL_CACHE_DIR`). - Was #654: LunarG's loader with MoltenVK (the default) and KosmicKrisp (`RX_VK_DRIVER`; `LONGSHOT_VULKAN_LOADER`, `LONGSHOT_KOSMICKRISP`). - Fix `80a10018`: test_darwin_renderer's fixture declares main's `evicted_import_bytes` (#223). ### 3. MoltenVK descriptor limits (was #847) On MoltenVK a program a pushed set breaks gets an ordinary update-after-bind set (`layout_pushes()` in `vk_draw.cpp`); every other driver pushes as before, and the SPIR-V and the caches are unchanged. - Was #643: storage buffer tables (vendor fix `set_for_tables`, `RX_VK_SET_FOR_TABLES`). - Was #644: programs that read a storage buffer's length (`gpu/vk/spirv_lengths.h`; `set_for_lengths`, `RX_VK_SET_FOR_LENGTHS`). - Was #645: stages with more than 8 storage images and storage texel buffers. - Was #646: stages past a Metal function's buffer, texture or sampler table; update-after-bind pools. - Fix `b56a6cee`: main's Linux pressure fixture includes `spirv_lengths.h` (#223). ### 4. The SPIR-V back end and guest spans on MoltenVK (was #848) Each part is chosen by a `Profile` flag `make_profile` sets on Apple, or by `alias_isolation` (macOS); with them off every module, layout and command is main's (the fixtures check it byte for byte). - Was #647: the segment planner for guest spans past one device allocation (`gpu/vk/span_segments.h`). - Was #648: piece arrays in the back end (`RuntimeInfo::segmented`). - Was #649: texel carrier codecs for ten formats MoltenVK cannot view (`texel_codec.h`; `RX_VK_TEXEL_CODECS`). - Was #658: guest buffers admitted per operation, over-cap spans imported as segments (macOS). - Was #662, #663: the segmented consumers' contract, then the consumers (`span_xfer.h`), and stand-ins for empty slots (`null_dummies.h`). - Was #674: null descriptors emulated in the back end (`kProgramCacheFormat` 3). - Was #675, #698: storage image reads kept in program order (MoltenVK; KosmicKrisp). - Was #676, #692: SPIRV-Cross's expression nesting bounded (`msl_depth.cpp`). - Was #693: control-flow nesting bounded at 128 (`msl_scope.cpp`). - Was #686: Rosetta host imports at whole 16 KiB pages, a refused import asked again only when its backing changes (`import_hold.h`). - Was #694: vertex stages run the guest's warp operations as one-lane warps. - Was #695: `RX_VK_SPV_PROFILE`, what the big modules are made of (log only). - Was #696: storage buffer tables searched in loops (`RX_VK_GM_LOOP` on MoltenVK and KosmicKrisp). - Was #697: local memory zeroed by a loop (`RX_VK_LOCAL_ZERO_LOOP`). - Was #787: giant mesh fallbacks' shape through the real back end (test only). - Port `8e3c5951`: a stand-in clear not done in 5 s is waited for before its fence and pool go (the Mac-only part of #788); `81eff678` keeps it inside `#if defined(__APPLE__)`. - Fixes: `7f9a99fa` (the profile fixtures where #694, #696, #697 and #698 meet), `74d8a42b` (the segment fixtures take main's FlatMap `c1_at`, #231), `30627309` (main's Linux pressure fixture stands in for `SegSig`'s `SegEntry`). ### 5. Precompile and pipelines on Metal (was #849) Under the vendor fix `compiler_service` (MoltenVK and KosmicKrisp only) the preparation compiles no compute pipeline, the precompile orders the work for Metal's compiler service, lets the title come while the last giants build behind the game, bounds giants and heavy compiles, and retries a failed compile alone (`gpu/vk/precompile_handoff.h`, the precompile in `vk_draw.cpp`). - Was #650: a pipeline cache per preparation worker, every CPU; no saved pipeline cache on MoltenVK (`worker_caches.h`, `prepare_workers.h`). - Was #651: renderer threads start with a 16 MiB stack on macOS (`gpu/vk/thread_stack.h`). - Was #652: the precompile goes on behind the title; slow compiles named. - Was #664: compute pipelines left to the precompile; at most 4 giants in flight (`seed_compute`). - Was #665: giants held until the first frame, at QoS class utility; a failed giant retried alone. - Was #666: a dispatch's compile goes ahead of the giants and is retried alone (`skip_log.h`). - Was #667: `RX_VK_METAL_ARCHIVE_DIR`, Metal binary archives (`metal_archive.h`; off). - Was #669: giants start behind the game only while memory allows; a lost device said as one. - Was #681: `RX_VK_LMEM_LOG` (`private_memory.h`; log only). - Was #784: heavy compiles run alone. - Was #785: KosmicKrisp's compiles through the compiler service, as MoltenVK's. - Was #786: Metal's cache folder asked at the host's start, before SDL's window (`host/posix/darwin_metal_cache.h`). - Ports: `e1965d56` (a never-ending compile holds the heavy ones back 240 s at most), `3c23a8e9` (slow-first: what an earlier run found slow compiles first), `cb01f764` (`metal_archive.h`'s notes). - Fix `30252cf5`: Metal's compiler service out of reach: compiles wait or are asked for again, no try alone spent (`ServiceReach`; run N3 lost 7,932 compute pipelines that way). - Fixes: `ad1147cb`, `69be3fd1`, `d450bc17` (tests where two members met), `42cc9868` (main's Linux pressure fixture includes `private_memory.h`). ### 6. Draw-path emulation on MoltenVK (was #850) - Was #677: polygon modes and restart-off strips counted on Apple (`mode_census.h`; log only). - Was #678: a direct draw's 8-bit indices bound with their size (`VK_KHR_maintenance5`; `RX_VK_INDEX8_SIZE`). - Was #679: count draws rewritten on the GPU without `drawIndirectCount`, buffer updates copied from the stream (`count_draws.h`). - Was #680: direct draws that read the draw index drawn as one indirect record (`drawid_direct.h`). - Was #691: docs: MoltenVK main 5189f8de with the argbuf-slots patch as the recommended input (`docs/macos-moltenvk.md`). - Was #701: fans keyed apart from the other triangle topologies (`fan_key.h`; the program cache stamp). - Was #702: an indirect fan of more than one record drawn a call a record (`fan_indirect.h`). - Was #703: flat values from each primitive's last vertex, as NVN (`provoking.h`). - Fixes: `8e3cbac6` (test_fan_indirect's cut), `6551f4c5` (`draw_index8_report`'s brace), `e0cc1407` (test_fan_key reads main's `predicted_keys_read()`, #713). ### 7. Indirect quads and mesh count draws on every driver, with their Mac halves (was #851) - `a10d6c62` (was #705, every driver): indirect quad draws drawn: their records rewritten on the GPU into indexed triangle lists (`gpu/vk/quad_draws.h`, `quad_draws.comp`, `quad_rewrite` in `vk_draw.cpp`). - `fbaba871` (was #707, every GPU on the mesh compute fallback): mesh count draws drawn, the records area grown past 64 MB when the allowance holds it, the cuts counted (`mesh_area.h`, `count_draws.h`, `host/nvn_native.c`). - Was #706: quads provoke the same corners where the first vertex provokes (Apple). - Was #708: the fallback's rotation follows the count draws and the grown area (Apple). - Fixes: `a39f027d` (#705 with area 6's censuses and checks), `af4f2999` (test_drawid_direct pins #707's DrawIndex condition). ### 8. Mac performance (was #852) - Was #704: frame cost lines, a GPU timeline and the bench's A/B arm, every platform, off by default (`vk_perf.cpp`, `perf_lines.h`). - Was #780: LoadClear; dropped again by `506752c2` (measured under the noise). - Was #782: restart-off 8-bit draws fetch vertex 255 as NVN does (`RX_VK_INDEX8_RAW`); its look-ahead dropped by `95aa6b91` (measured under the noise). - Was #783: the mesh fallback's draws of a pass batched in one pass (`mesh_batch.h`; `RX_VK_MESH_BATCH`). - Ports: `ebf9d527`, `615e698e` (no provoking-vertex draw left out in a mesh batch; the every-platform middle commit is #853), `f9b1c81b` (macOS's write-mark walk, 64 marks a test in 16-byte loads; `collect_in` in `host/rx_backend.c`, `HOS_COLLECT_VECTOR`). - Fixes: `df8c1602`, `18bf99b2`, `325a9147`, `7c0a8884` (tests where two members met), `b0326575` (the perf-lines and stream-room tests read main's `split_part` and FlatMap, #443, #231). The join: `8d337c08` merges area 5 into areas 6-8's line (Reviewer notes); `6343f29e` names #707's new fallback bind under `RX_VK_LMEM_LOG`, as #681 names the other fallback binds (log only; found by `test_private_memory` at the join). Docs: `docs/development.md` (the macOS build and every switch's row), `docs/control.md`, `docs/pipeline-cache-storage.md`, `docs/macos-moltenvk.md`, `gpu/vk/VULKAN.md`. ## Measurements **Verdict:** works. Main cannot build on a Mac; with this PR's commits (integration builds) the game held 1,197 s in play on arm64 and 18 m 22 s under Rosetta from the field-dawn save, every draw drawn, all eight heavy compiles made, no device loss, a clean exit. Two changes measured faster on the same build and ship on: MeshBatch (−1.0 ms a frame) and macOS's vector walk (the replay's memory sync 3.25 → 0.25 ms a frame); two measured under the noise and are dropped (LoadClear, Widen8's look-ahead). Hardware: macOS 26.7.1 (25G241), Apple M4 Max (40-core GPU), 16-core CPU, 64 GB; MoltenVK main 5189f8de + argbuf-slots (arm64 `c170a745`; its x86_64 slice `96313ca8` under Rosetta) Scene: Hyrule Field from the field-dawn save (slot 00, START then A), windowless unless named, LS's defaults; frame cap 60 for I39's E-series (E7: 240, which never binds), `HOS_FPS_MAX=240` for E9 Method: each run's longshot_log.txt (the precompile, hand-off, compile and close lines; the FPS counter's Dev level; `RX_VK_PERF_LINES`' L1-L6), medians over the hold's 120-present periods from +20 s; one start each (E7 against E2 measured the run-to-run noise: 0.17 ms of frame) How to reproduce: `tools/ls-run.py` (the port's runner) on a macOS build of these commits, the field-dawn save, START and A at the title; the switches in each column Baseline: main @ 7bacf846 does not build or start on macOS, so the after columns are the port's integration builds I41 `78ec1c47` and I42 `63fc3d2c` (I41 plus slow-first), which carry these commits as they were before the rebase onto 7bacf846 (without `30252cf5` and the Sweep4 test fixes; with the every-platform #788 and #853, which are separate PRs). The A/Bs below compare one build with a switch off and on. No game run at this PR's head yet (Testing). | | Before: main @ 7bacf846 | After, arm64 (E9a): integration @ 78ec1c47 | After, x86_64 under Rosetta (R39): integration @ 63fc3d2c | |---|---|---|---| | builds and packages on macOS | no: the builder takes the Linux route | yes | yes | | start to the title and play | no | hand-off 8 m 14 s after the start, play 48 s later | hand-off 9 m 42 s, play at 10 m 48 s | | held in play | - | 1,197 s | 18 m 22 s (a 1,093 s hold) | | skipped draws / provoking-vertex draws left out, in the hold | - | 0 / 0 | 0 in 214 hold groups / 0 | | heavy compiles (4 giant mesh programs, 4 others) | - | 8 of 8 made, 0 XPC errors | 8 of 8 made, 0 XPC errors, 0 `[mvk-error]` | | 44511d69 (the field's tree leaves) | - | made 895.6 s into its compile | first in the precompile, made 1,115.8 s after the start | | device loss, exit | - | none; exit 0, clean end, 0 crash reports | none (0 IOGPU/AGX lines); clean exit | | the runs' checks | - | 12 of 12 must-shows | 15 of 15 must-shows, 18 of 18 RosettaImport checks | | frame rate in the hold | - | 37.1 fps, 26.95 ms, GPU 19.4 ms | 23.5 fps under load 14.7, GPU 20.2 ms | ``` E9a (mac-arm64-78ec1c47-01): precompile 479.0 s, hand-off 07:23:28.6, play 07:24:16, hold 07:24:25.3-07:44:22.6; 12 of 12 checks true giants: 5096bcc7 50.2 s, 6dbfda5a 29.9, 5c945415 34.1, 55d1da3f 34.1; 44511d69 895.6 s; 0 XPC errors; 0 "not made"; skips 0 in the hold R39 (mac-x86-63fc3d2c-01): 47798 program keys kept; hand-off L32179 "41877 of 42137 done"; play-hold 656.9-1,750.4 s; 25,565 frames in 1,090.0 s #38 (mac-arm64-63fc3d2c-01, windowed 1280x752): 148 hold groups all "0 skipped"; 32.79 frames/s over 540 s; 44511d69 made 986.1 s after the start ``` The windowed run #38 (I42) held 540 s, 0 skipped draws, the tree leafy from its shot after 44511d69 was made; its lane's death cut the hold at 542 s (the game quit on request, exit 0). The owner looked at E9a's shots in Preview. **The speed-ups** (same build, switch off against on, one 600 s hold each): | field-dawn hold | Before (switch off) | After (as it ships) | |---|---|---| | MeshBatch, I39 `7a7726fe`, E4 → E2: fps / frame ms / GPU ms | 32.6 / 30.67 / 20.2 | 33.7 / 29.67 / 19.1 | | MeshBatch: pass ends a frame / MB loaded and stored a frame | 188.0 / 649 | 133.9 / 378 | | vector walk, I41 `78ec1c47`, E9b (`HOS_COLLECT_VECTOR=0`) → E9c: the replay's memory sync, ms a frame | 3.25 | 0.25 | | vector walk: frame − GPU ms / a capture's scan, ms a submit | 10.74 / 0.190 | 7.58 / 0.020 | | vector walk: frame ms (fps) | 33.56 (29.8) | 27.10 (36.9); about half is GPU time the walk is not shown to cause: about 3.1 ms at equal GPU time | | LoadClear (E4c → E2), Widen8's look-ahead (E4b → E2): frame ms | 29.67 each | 29.67: under the noise, both dropped | | MeshBatch, LoadClear and Widen8's look-ahead together, E3 → E2 (what ships is E2 within the noise; uncapped, E7: 33.9 fps) | 32.3 fps, 30.96 ms | 33.7 fps, 29.67 ms | Across builds, not A/Bs: MoltenVK 1.4.2 → main 5189f8de + argbuf-slots, GPU 23.1 → 20.25 ms a frame (#691's starts); with `RX_VK_INDEX8_RAW`, MoltenVK's 8-bit pass splits 57.5 → 0 a frame (I38 → I39). MoltenVK's asynchronous submits measured 0.63 ms slower (E6): not adopted. The every-platform present-nowait (#656) measured no gain on this Mac (E10). **What each area fixed**, as each original PR measured it (its build or GPU probe named; history): | area (was) | Before | After | |---|---|---| | 2 unified budget (#642): the GPU allowance | 53,084 MB, the driver's (run #22 lost the device) | 10.2-20.8 GB, read from the system (runs #24, #26) | | 2, 5 Metal's cache folder (#653, #786) | denied cache opens about 1.5 a compile; windowed start to hand-off 24 m 28 s (#35) | 0; 6 m 53 s (#36) | | 2 drivers (#654): the start's preparation | - | MoltenVK 38,809 programs in 58.0 s; KosmicKrisp 1,607 in 1,770 s, no title: MoltenVK stays the default | | 3 descriptor limits (#643-#646): pipelines lost at the first start | 256 (alias errors) | 0, arm64 and Rosetta | | 4 back end (#696; #697): pipeline creation (GL-01; LM-01/02) | 15.36 s; 7,518 ms at 64 KiB local memory | 1.45 s; 15-16 ms | | 4 back end (#693; #694): Metal's refusals (CG-01; SG-01) | refused past 256 braces; 14 vertex pipelines refused | made, exact words; 19 of 19 | | 4 Rosetta imports (#686) | about 1,640 draws a frame left out (refused imports) | 0 refused imports (runs #33, #34) | | 5 preparation (#650; #664) | 39 programs in 180 s; 1,550.4 s compiling 1,381 compute pipelines | 230; 118.3 s with none | | 5 thread stacks (#651) | SIGILL in SPIRV-Cross at about 93 s (start #6) | starts #7-#9 clean | | 5 precompile (#652; #665) | no title (run #12); first frame 188-198 s after the hand-off | title (run #17); 5.0 s | | 5 slow-first (port): 44511d69 made, from the start | 1,439.9 s (E9a) | 986.1 s (#38) | | 6 8-bit indices (#678): GPU memory loading the first scene | 53.1 GB, out of memory, device lost | 9.3 GB in play | | 6 draw index; fans; flat values (#680; #701; #703), MoltenVK probes | 1,688 of 3,744 stale; 96 of 288 wrong; the first vertex's | 0; 0; the last vertex's (NVN's), every pixel | | 7 indirect quads; mesh count draws (#705; #707), every driver | left out | drawn: equal to the direct path's quads (QD-01, 41 of 41) and to each record drawn alone (MC-01, 29 of 29) | | 8 provoking-vertex draws in batched passes (stream-room port) | 0.6-0.9 left out a frame (run #36) | 0 (E9a) | ### Flags and settings The switches and build inputs, in area order: new ones read on macOS or MoltenVK/KosmicKrisp only; three measuring switches (`RX_VK_PERF_LINES`, `RX_VK_GPU_TIMELINE`, `RX_VK_BENCH_AB`) on every platform, off by default; nothing changes off the Mac with them unset. `RX_VK_LOAD_CLEAR` and `RX_VK_WIDEN8` are gone again (measured under the noise). Main's switches the diff shows, read as before: `RX_VK_DLSS_ACTORS`, `RX_VK_GPU_DUMP`, `RX_VK_MESH_IND_COUNT_WORD`, `RX_VK_NO_UPSCALE_STUB`, `HOS_HEADLESS`, `RX_VK_NO_WARM`, `RX_VK_PCACHE_FETCH_LOCK`, `RX_VK_SKIP_PROG`, `RX_VK_BENCH`, `RX_VK_CHUNK`, `RX_VK_DRAW_STATS`, `RX_VK_PASS_BARRIER`, `RX_VK_PASS_TIMING`, `RX_VK_BARRIER_DEDUPE_OFF`, `RX_VK_BARRIER_EVERY_DRAW`, `RX_VK_PUSH_STATE_OLD`, `HOS_COLLECT_WIDE`. | Flag | What it is | Before this PR | After this PR | Effect | Helps / doesn't help / untested | Recommendation | |---|---|---|---|---|---|---| | `RX_VK_LIBRARY=<path>` | macOS: the first Vulkan loader or MoltenVK dylib to try | not read | unset: the one beside the game | the renderer and SDL load it first; a bad path logged, the next tried | helps on macOS; untested on an Intel Mac | unset | | `RX_ARCH=arm64` or `x86_64` | the macOS build's architecture | (macOS built as Linux) | arm64 on Apple silicon, x86_64 on an Intel Mac | the Mach-O target | macOS only | x86_64 for the Rosetta route | | `LONGSHOT_MOLTENVK` | macOS build input: the MoltenVK dylib | not read | required on macOS | packaged as `libMoltenVK.dylib` | recommended: main 5189f8de + argbuf-slots (`docs/macos-moltenvk.md`; 0 lost pipelines); 1.4.2 accepted | the recommended build, once approved | | `LONGSHOT_SDL3` | macOS build input: SDL3 for SDL2-compat | not read | unset; required when the SDL2 dylib names SDL3 | packaged as `libSDL3.0.dylib` | untested: SDL2-compat loading it in a game | set beside `LONGSHOT_SDL2` | | `LONGSHOT_DARWIN_ARCHIVE_RECEIPT`, `LONGSHOT_DARWIN_ARCHIVE_RECEIPT_SHA256` | the receipt for FFmpeg's NASM members without a minimum-macOS command, and its digest | not read | unset: such members refused | admits exactly the receipted members | x86_64 FFmpeg with NASM only | set both for that FFmpeg | | `LONGSHOT_VULKAN_LOADER`, `LONGSHOT_KOSMICKRISP` | macOS build inputs: LunarG's loader; KosmicKrisp (arm64) | not read | optional, unset | the package carries the loader and a manifest per driver | lets one package measure both drivers | for measurement packages | | `RX_MARCH`, `EMSDK`, `SDKROOT`, `LONGSHOT_FFMPEG`, `LONGSHOT_SDL2`, `RX_VK_ONLY` (existing) | CPU level, LLVM prefix, Apple's SDK, FFmpeg, SDL2, a renderer-only build | read on a Mac as on Linux | Mac defaults (arm64: no x86 level; x86_64: x86-64-v2); SDL2 packaged | the macOS build works | Windows and Linux unchanged | the Mac defaults | | `LONGSHOT_NGX_SDK`, `LONGSHOT_FSR` (existing) | NVIDIA NGX's SDK, AMD's FSR runtime | read on a Mac as on Linux | macOS: the build stops, "no macOS build" | no NGX or FSR on a Mac | neither has a macOS library | unset on a Mac | | `HOS_PROFILE`, `HOS_THREAD_TIMES`, `HOS_SAMPLE`, `HOS_SAMPLE_ALL`, `HOS_SAMPLE_FILE`, `HOS_CHAIN`, `RX_MAPS` (existing) | the host profiler, sampler and maps | no macOS route | on macOS as on Linux | profiling on a Mac | untested in a game run | profiling only | | `HOS_WATCH`, `HOS_PIN_BY_CORE`, `HOS_PIN`, `HOS_RESERVE_CORE` (existing) | watchpoints, pinning, the reserved core | no macOS route | on macOS each says once it is unavailable | none on macOS | by design | unset on macOS | | `HOS_ZERO_ALL_PAGES`, `HOS_KEEP_FREED_PAGES`, `RX_NVN_WATCH_TEXELS_SRC`, `RX_NVN_WATCH_AFTER`, `RX_NVN_WATCH_ALL` (existing) | guest-memory and write-watch debugging | 4 KiB-page assumptions on macOS | 16 KiB host pages, main's meaning | debugging works on a Mac | Windows and Linux unchanged | debugging only | | `RX_VK_UNIFIED_BUDGET=0` | the GPU allowance the driver's again | (the driver's) | on, on a Mac's unified memory | budgets follow what the Mac has free; `vk: unified memory` line | helps: memory pressure; untested: 8-32 GB Macs | on; `=0` only to compare | | `RX_VK_METAL_CACHE_DIR=<folder>` | Metal's shader cache folder | Metal's own under `/var/folders` | unset: unchanged | sandboxed or carried starts find a warm cache | helps: sandboxed runs (#36); no effect on a normal start | off; set for sandboxed runs | | `RX_VK_DRIVER` | macOS: `kosmickrisp` or `moltenvk` on a loader package | (no switch) | unset: MoltenVK | the driver the loader is given | `kosmickrisp`: measurement only (run #20, no title) | unset | | `RX_VK_SET_FOR_TABLES`, `RX_VK_SET_FOR_LENGTHS` | `0` or `1`: ordinary sets for the programs a push breaks on MoltenVK | (pushed) | unset: on with MoltenVK only | those pipelines made, lengths exact; a close line counts the moves | helps: MoltenVK (256 lost → 0); untested: the sets' cost | unset | | `RX_VK_TEXEL_CODECS` | `0` or `1`: texel buffers through carrier codecs | (native views) | unset: on on macOS when a format query fails | those programs translated with codecs | helps: macOS; untested `=1` elsewhere | unset | | `RX_VK_SPV_PROFILE`, `RX_VK_SPV_PROFILE_MIN` | a line per big module, from that many SPIR-V words | (no switch) | off; 100000 | log lines; translation slower | diagnosis | off | | `RX_VK_GM_LOOP` (existing) | storage buffer tables searched in a loop | Intel's Mesa driver only | also MoltenVK and KosmicKrisp | smaller Metal source | helps: GL-01 (15.36 → 1.45 s) | unset | | `RX_VK_LOCAL_ZERO_LOOP=0` | local memory zeroed by its initializer again | (the initializer) | the loop on MoltenVK | smaller Metal source | helps: LM-02; no effect elsewhere | unset | | `RX_VK_COMPILER_SERVICE` | `0` or `1`: the compiler-service preparation and precompile | (no switch) | on for MoltenVK and KosmicKrisp | area 5's order, bounds, hand-off and retries | helps: MoltenVK (runs #17-#38, E9a) | as it ships; `=0` to compare | | `RX_VK_WORKER_CACHES` | a pipeline cache per preparation worker | (no switch) | on for MoltenVK | compiles side by side | helps: 4.4-4.6× pipelines a second | as it ships | | `RX_VK_PCACHE_LOAD` (existing default) | the pipeline cache file read and saved | read and saved everywhere | MoltenVK: neither; elsewhere as before | a later MoltenVK start compiles anew | helps: 1.41 s against 6.65 s | as it ships | | `RX_VK_SLOW_COMPILE_S`, `RX_VK_PRECOMPILE_STALL_S` (the second existing) | slow-compile seconds; nothing finished before the game starts | (none); 30 once all handed out | 10; 30 whatever is left | slow compiles named; the title not held by giants | helps: MoltenVK | as it ships | | `RX_VK_GIANT_COMPILES`, `RX_VK_GIANT_WORDS` | giants in flight; words that make a giant | (no switch) | 4; 100000 | small items finish beside giants | helps: runs #18, #19 | as it ships | | `RX_VK_GIANT_HOLD_PRESENTS`, `RX_VK_GIANT_HOLD_S`, `RX_VK_GIANT_ROOM_MB` | giants held after the hand-off; the longest hold; memory one giant gets | (no switch) | 1; 120; a quarter of memory, 16384 at most | the first frame comes first; giants wait for memory | helps: starts 21-24; the room gate untested in a game | as it ships | | `RX_VK_COMPILE_QOS` | QoS class of giants and work behind the game | (no switch) | utility | Metal serves the game's compiles first | untested against `default` in the game | as it ships | | `RX_VK_ALONE_TRIES`, `RX_VK_SKIP_LOG` | tries alone per program; each dispatch left out named | (no switch) | 2; off | a compile failed beside a giant is made, not lost | untested in a game (no such failure) | as it ships | | `RX_VK_HEAVY_WEIGHT`, `RX_VK_HEAVY_WORDS`, `RX_VK_STALE_COMPILE_S` | what makes a compile heavy (runs alone); when a compile in flight stops holding them | (no switch) | 10000000; 1000000; 240 s | the four giant mesh programs made | helps: GC-02, E9a (all eight made) | as it ships | | `RX_VK_SLOW_FIRST_S` | an earlier run's compile time from which it goes first | (no switch) | 240 | 44511d69 begins with the precompile | helps: #38 (986.1 against 1,439.9 s), R39 | as it ships | | `RX_VK_SERVICE_BURST`, `RX_VK_SERVICE_FAST_MS` | failures in a row, each this fast, that mean Metal's compiler service is out of reach | (no switch) | 8; 250 ms | compiles wait or are asked again, no try alone spent | untested in a game (run N3's case, game-free) | as it ships | | `RX_VK_METAL_ARCHIVE_DIR` | macOS: MoltenVK's pipelines in Metal binary archives | (no switch) | unset: off | a start makes earlier starts' pipelines without compiling | helps: ARC-2 (24,251 from archives); doesn't: +29 GB footprint | off | | `RX_VK_LMEM_LOG`, `RX_VK_LMEM_LOG_MIN` | macOS: each module's private memory logged, from that many bytes a thread | (no switch) | off; 1024 | log lines | diagnosis | off | | `RX_VK_INDEX8_SIZE` | `0` or `1`: a direct draw's 8-bit indices bound with their size | (bound to the pool's end) | on for MoltenVK only | MoltenVK widens only the draw's indices | helps: 53.1 → 9.3 GB (runs #23, #24) | as it ships | | `RX_VK_COUNT_REWRITE=1` | the count-draw rewrite where the device has `drawIndirectCount` too (macOS) | (no switch) | off: the rewrite only without the feature | compares the rewrite with the driver's | untested in a game | off; for testing | | `RX_VK_PERF_LINES=1`, `RX_VK_GPU_TIMELINE=1` or `2`, `RX_VK_BENCH_AB=<arm>` | every platform: frame cost lines; the GPU timeline; the bench's B arm | (no switch) | off | log lines; relaxed counters | helps: measuring (the E-series) | off; for diagnosis | | `RX_VK_INDEX8_RAW` | `0` or `1`: restart-off 8-bit draws fetch 0xFF as vertex 255 | (MoltenVK's 0xFFFF: primitives lost) | on for MoltenVK only | NVN's primitives | helps: W8-01 r2 (14 of 14) | as it ships | | `RX_VK_MESH_BATCH` | `0` or `<n>`: the mesh fallback's draws of a pass batched | (each breaks its pass) | on for MoltenVK, 8 members | 54 fewer pass ends a frame | helps: −1.0 ms frame (E4 → E2) | as it ships | | `HOS_COLLECT_VECTOR=0` | macOS: the write-mark walk a byte load each, as before | (no switch) | the vector walk | the same pages, order and marks | helps: −3.0 ms memory sync (E9b → E9c) | as it ships; `=0` for A/B | ## Testing ### Current revision validation (`594d5296`) **Tested:** game-free validation of the `594d5296` source on this Mac, as detailed below; no current-revision game or Windows/Linux run is claimed. - The working-source snapshot was verified against the committed tree. The main merge resolves descriptor-array atomics, compute-pipeline publication, segmented writes/import lifetimes, Darwin link/package handling and updated fixtures; no archive or NETWORK_KEEP default was enabled. - The full source run before fixture repairs was **670 passed, 31 failed, 17 skipped**, against matching main `a8a30c22` at **584/43/18**. Six merge-related fixture failures were repaired and all six passed focused reruns. A Windows-only execution test gained its explicit macOS skip; the ordinary runner excludes it and still includes the passing portable report test. No new full-suite total is claimed after those fixture-only edits. - **20 whole-file compiles passed**, covering the changed runtime translation units on arm64 and x86_64. Runtime/build/header sources stayed unchanged during the subsequent fixture repairs. - **36 synthetic image-array SPIR-V modules validated**. Renderer linkage passed **1,218 name/architecture checks**, with all **631 cross-file symbols per architecture** resolved. Existing compiler extension warnings were retained, not represented as a warning-free build. - No game run or Windows/Linux execution has yet qualified this revision. The game-run and broader earlier-compilation evidence below belongs to its stated earlier commits. ### Earlier validation (`6343f29e`) **Earlier tested revision:** macOS 26.7.1, Apple M4 Max, 16-core CPU, 64 GB, Apple clang 21.0.0, at `6343f29e` on main `7bacf846`, arm64 and x86_64 under Rosetta; these results are historical, not a fresh run of `594d5296`: - The full game-free suite (`python -I -B tests/run_all.py` through `tools/ls-suite.py`), compared by test name with main `7bacf846`'s on this Mac: 649 passed, 16 failed, 17 skipped, against 558/34/17. New and passing: the 73 new tests. Fixed (FAIL on main): 17, the host's macOS repairs (`test_collect_wide`, `test_control`, `test_crash_record`, `test_longshot_ctl`, `test_low_memory_notice`, `test_prof_symbols`, `test_mem_gate`, `test_mem_gate_children`, `test_mirror_trim`, `test_oot_state_tap`, `test_report_run` and six cache checks). `test_appimage_package_retry` is skipped on macOS by #454's declaration, and `test_dav1d_av1` runs and passes (#454 links dav1d). Nothing that passes on main fails. The 16 failures fail on main too, on this Mac: `test_appimage_player_build`, `test_crash_dialog`, `test_env_on`, `test_game_layout`, `test_lift_cleanup_error`, `test_linux_preflight`, `test_make_game_cache`, `test_missing_nup`, `test_options_budget_once`, `test_options_path`, `test_pipeline_tour`, `test_readback_late`, `test_split_giants`, `test_vk_occlusion_queries`, `test_vk_pgo`, `test_walk_key`. - The original PRs' own tests and the tests each area's range touches: 482 jobs (222 arm64, 194 x86_64, 20 both in one run, 46 without an architecture), 459 pass. The 23 others are explained, none a defect of this head: 16 base-tree checks of area 4 (`test_seg_shader --base-tree` against seven old member bases, `test_local_zero --base`) differ from those bases only in the mesh fallback's modules, which #707 (area 7) changes on purpose (they pass up to area 6); the consumer-check job, 54 of its 60 cases as required; 4 runs of main's own failing `test_vk_occlusion_queries`; 2 of #667's old `test_metal_cache_dir --headers` form (#786's form passes). 33 jobs passed on a second run: Rosetta SIGKILLs under load (exit -9, no crash report), and runs repeated after a fix. - Open note, area 4's consumer checks: the `seg-bind` positives (both arches) report "common path differs from B2's cut" because they compare with B2 `918e6214`, from before main `7bacf846` changed the functions they cut (the same at area 4's own tip); the `seg-gathers` and `seg-xfer` positives cannot build B2 with today's fixtures, which include areas 6 and 8's headers (they pass at area 4's tip). `test_seg_bind`, `test_seg_gathers` and `test_seg_xfer` themselves pass at this head, both arches. - Whole-file compiles of the 59 non-test C/C++ files this head changes: 46 with the tree's own `nx2/build.py` macOS commands (104 compiles, arm64 and x86_64) and the 12 `gpu/vk/eden` back-end files with the renderer library's flags (24 compiles): 128 compiles, all exit 0; `nx2/bake_ds/bake_ds.cpp` (a Linux lift tool) through its member test. - The renderer's link check (each defining `gpu/vk` file compiled with the tree's `renderer_flags()`, arm64 and x86_64): 68 of 68 objects, 610 cross-file `mkwvk::` symbols per architecture, every one defined. - Off Apple (`unifdef -U__APPLE__` of the 130 changed non-test C/C++ files against main, compared as tokens): 16 the same, 55 differ, 59 new (11 of them only Apple blocks). Each area's off-Apple change, compared at its tip with its original PRs' before the rebase, is that change or differs by the rebase's hand resolutions only (Reviewer notes); the join adds nothing off Apple but `6343f29e`'s log-only line. What differs is listed under Risks. - Each area at its own tip, before the join: compiles and link checks all exit 0; suites at the rebased tips 587/16/17, 589/18/17, 559/35/17, 614/20/17, 627/20/17, 621/21/17, 626/22/17, 629/23/17 (areas 1-8), whose new failures led to the seven fixture fixes named above (beside the load-sensitive `test_gpu_hang_watch`). - In the game (integration builds, before the rebase; Measurements): E9a on I41 (arm64, 1,197 s), R39 on I42 (Rosetta, 18 m 22 s) and #38 on I42 (windowed, 540 s); earlier, #32 on I38 (arm64, 900 s) and #34 on I38 (Rosetta, 16 m 52 s). **Not tested:** Windows and Linux execution of the current revision; a game run of `594d5296`. The game runs below are earlier integration builds without `30252cf5`. No scene with an indirect quad draw or a mesh count draw (field-dawn draws neither: E9a has no `vk: quad draws` line and `vk: mesh draws` 0.0 a frame with a count), so area 7's every-driver paths ran only in the tests and the QD-01 and MC-01 probes, never on a GPU with mesh shaders or another driver's fallback. A segmented domain in a game; KosmicKrisp in a game beyond run #20; a warm start from Metal binary archives as shipped (off); a Rosetta frame rate in a quiet hold on I42; Macs with 8-32 GB; macOS 14.4 and 15 (every run was on 26.7.1); an Intel Mac; SDL2-compat loading the packaged SDL3 in a game. **Must be tested:** - Windows and Linux, any GPU: build this PR (head `594d5296`) and main `a8a30c22` the same way, run `python -I -B tests/run_all.py` on each and start each to the title, expecting successful builds and no regression against that main, with every unsupported check explicitly declared (by hand: compare the suite results and renderer/cache startup logs). T-3F2Q was opened for the earlier `6343f29e`; it is not acceptance evidence for this updated head. Current-head qualification is required before ready. - Windows and Linux, a GPU on the mesh compute fallback and one with mesh shaders: (fallback GPUs: GTX 10xx, RX 5000, AMD on Linux by default, Navi 21/22 on Windows) play to the field with `RX_VK_VALIDATION=1`, expecting `vk: quad draws (…)` with 0 left out once a quad is drawn, `vk: mesh draws (…)` with none left out, `vk: mesh fallback cuts so far` all zero on the fallback GPU, no validation error, no `vk: provoking vertex` line and the scenes as on main (by hand: T-3F2Q, with screenshots of anything that differs) - Windows and Linux, any GPU: start this PR once more with `RX_VK_PERF_LINES=1 RX_VK_GPU_TIMELINE=1` and play a minute, expecting the `vk: L1`-`L6` lines and a T1 line every 120 presents, the frame times as without them (by hand: T-3F2Q) ## Risks **What could break:** on Windows and Linux, by intent: every driver now draws indirect quad draws and every GPU on the mesh compute fallback draws mesh count draws, both left out before (a pass break per indirect quad draw, device-wide buffers made at the first one; the fallback's records area can grow past 64 MB; fallback stages that load DrawID read it pushed); a startup that fails part-way unwinds what it made; on Linux, Discord presence's socket code and the thread-creation error paths; the build's Windows and Linux arrays moved into functions (pinned element for element). Compiled everywhere but gated off at run time: the back end's new emit paths, the descriptor-set choice, the compiler-service precompile, the draw-path fixes, MeshBatch; a gate held wrong would change modules or commands off the Mac (the fixtures check the modules byte for byte against main's). The perf hooks cost one flag load each with their switches off (about 1 ns a call). On macOS everything is new and has run game-free and in the integration builds only: the start's order under the compiler service; sets instead of pushes, null-descriptor guards, stored image reads and one-lane warps cost what no frame has measured. **Turning it off:** the macOS code is behind `__APPLE__` or a driver gate; the switches above turn its parts off (`RX_VK_COMPILER_SERVICE=0`, `RX_VK_MESH_BATCH=0`, `RX_VK_UNIFIED_BUDGET=0`, `RX_VK_SET_FOR_TABLES=0`, …). The every-driver draws of area 7 have no switch: revert their two commits (was #705, #707), or the PR. **Compatibility:** every platform lifts the game again once (`nx2/kit.py` and the new `nx2/darwin_toolchain.py` are lift sources), prepares its shaders again once (the translator's stamp changes: `vk_shader.cpp`, the back end, the fallback's DrawID), rebuilds its program cache once (`kProgramCacheFormat` 1 → 3) and compiles the host's objects again once. The vk ABI: `MKWVK_API_VERSION` is 27 on macOS only (host slots appended by #438, #491, #686 and #786; the macOS executable and renderer are built together); Windows and Linux keep main's 23 with the same structure. Saves and `longshot_options.ini` are unchanged. Every platform's log gains fields: the `vk: vendor fixes` line (0 off MoltenVK), the quad and mesh draw reports. On MoltenVK the pipeline cache file is no longer read or written, and `longshot_pipelines.bin.slow` lists slow compiles. ## Reviewer notes **Reading order:** the areas in commit order. The every-platform parts to read closely: area 7's two commits (was #705, #707), #491's startup rollback (area 2), #490's Linux changes (area 1) and #704's measuring hooks (area 8). Then the Mac's: the build scripts and `host/posix/darwin_*.c` (1), `vk_memory.cpp`'s imports and the budget (2), `layout_pushes()` (3), the back end by `Profile` flag (4), `precompile_handoff.h` (5), `draw()` in `vk_draw.cpp` (6, 7, 8). **By commit:** `git log --reverse --no-merges --format='%h %s' 7bacf846..6343f29e`. Each original PR's commit names it (`Was: #NNN` with its branch; area 7's two say "#705 restacked …", "#707 …"); that PR's page keeps its review and measurements. The named fix commits sit after their area's members. The maintainers squash at merge. **Topology:** each topic's commits are linear on its base; the merges are the stack's own. ``` 7bacf846 ── #845 ── #846 ── #848 ──┬── #849 ─────────────────────┐ │ │ └── #850 ── #851 ── #852 ─────┴── 8d337c08 ── 6343f29e 7bacf846 ── #847 ────────────┘ │ 7bacf846 ── #431 (its own PR) ──┘ ``` #848 sits on #846 and merges #847 and #431; seven "Merge topic/<base> into topic/<name>" commits carry Sweep4's test fixes up the stack. #849 and #850 both sit on #848, so one merge commit, `8d337c08`, joins #849's line to #850-#852's: in its five conflicted files (`vk_draw.cpp`, `vk_main.cpp`, `vk_progcache.cpp`, `vk_replay.cpp`, `vk_vendor.h`) both sides add at one place, and the merge keeps both, in integration build I42's (`63fc3d2c`) order. Two more merges (`562d10b3`, `e9404d81`) take areas 4 and 5's last fixture fixes up, and `6343f29e` adds the one line where areas 5 and 7 meet. **Rebased onto main `7bacf846`** (from `aa95d35f`); the hand resolutions, each also in its commit's message: - `d85dac1a` (#453), `0e7ee58e` (#479): main dropped the WebGPU renderer (#577), so the macOS build has none; main's host-source line stays verbatim (main's `test_no_webgpu.py` unchanged), and the link takes `resources=exe_resources()` (#857). - `81c21324` (#491): main's `evicted_import_bytes` accounting (#223) kept before `destroy_import(p)`; `ec5731cc` (#642): main's Linux pressure kept beside the unified-memory `keep_now`. - #847: rebased by HumanBean on the forge (`88e914ad`); `vk_shader.h` keeps main's `record_at`/`record_size` and `array_length`. - `a9888f20` (#663): main's FlatMap `c1_at` (#231) with the segment arena; by the owner's decision on #403, main's generic dummies stay on every device without `nullDescriptor` (`make_dummies` and its test unchanged) and the typed stand-ins move to `make_stand_ins()`, Apple only. #431's merge takes its earlier resolution (`vk_memory.cpp` and two tests). - `64c14f29` (#651), `9ab883a4` (#665): include lines only. - #851 is linear now: #705 and #707 are one commit each at its base; the brace fix that once followed them is not needed. - `256ddf7e` (#704): the perf op before main's `split_part` (#443), its reason line inside it; `e26f6c09` (#783): main's `c1_at.reset()` before the mesh batch's start (`test_mesh_batch` asks for it, the owner's decision); `14cc564d`, `644770fc`, `506752c2`: the LoadClear and Widen8 lines around main's split. **Main integration:** `594d5296` has parents `6343f29e` and `a8a30c22`; the previously listed 19 conflicts with that main are resolved. Current-revision validation is listed above. Any newer upstream changes and the live mergeability state must be checked again before this PR is marked ready; no additional rebase or acceptance run is scheduled during the owner's hold. **Related every-platform PRs, kept separate:** #431 (merged inside #848; review it there; its two commits drop out of this diff once it lands); #853 (a direct quad draw's triangles grow the stream under `RX_VK_STREAM_GROW_OFF`: the every-platform half of area 8's stream-room port; merges cleanly with this PR); #907 (a direct non-indexed quad draw's BaseVertex is its first vertex, as area 7's indirect quads read it; conflicts with this PR in `vk_draw.cpp`); #936 (the write-mark walk vectorised on every platform, of which area 8's macOS walk is the Mac form; conflicts in `host/rx_backend.c`, `tests/test_collect_wide.py` and `docs/development.md`: whichever lands second takes the other's walk); #788 (async-safe frees; area 4 carries its Mac-only part; merges cleanly); #656 (present-nowait; no gain on this Mac). Independent of this PR: #423 #428 #434 #451 #452 #474 #475 #498 #670 #700 #912. These overlap notes were assessed at `6343f29e`; recheck them before integrating another PR. **Coming separately:** the macOS nightly builder (a zip for Apple silicon and CircleCI jobs), as its own PR on top of this one. ## Issues See #420. ## Checklist ### Everyone - [x] One topic. - [x] The title is a Conventional Commit (`type(scope): description`) of the status line's type. - [x] Why gives the reason plainly and links the issues that fit (the tracker searched). - [x] Measurements has a verdict, or one line saying why there is nothing to measure. - [x] Testing names what was tested, what wasn't, and what must still be tested, where and how. (Test request T-3F2Q.) - [ ] Rebased on current `main`: main `a8a30c22` is merged at `594d5296`; a final live-main check is owed before ready. - [ ] `python -I -B tests/run_all.py` passes (any failure that also fails on `main` is named). See current-revision full-run and focused-repair evidence under Testing; Windows/Linux and final game-build acceptance remain open. - [x] No game files, dumps, build output or generated files. - [x] `third_party/` untouched (a new folder with a `PROVENANCE.md` instead). - [x] The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled. ### When it applies - [x] AI assistance recorded with `Assisted-by:` / `Co-Authored-By:` trailers. - [ ] Numbers from the same PC, scene and settings, at least 2 interleaved runs each, the median reported. (Same PC, scene and settings and the hold's median, but one start each: E7 against E2 measured the run-to-run noise.) - [x] Switches documented (docs/development.md; the README for a menu row) and shipped at their recommended value. - [x] `MKWVK_API_VERSION` bumped (`gpu/vk/vk_api.h`'s `MkwVkHost` or `MkwVkRenderer` changed). (macOS 27; Windows and Linux 23.) - [x] The SPIR-V headers regenerated with glslang (a shader changed). - [x] A game-free test added for the fix, failing on `main` and passing here. - [x] A check under `tests/` that reads changed source updated in this PR, not weakened. - [ ] Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. (Not built there yet: the test request.) - [x] Docs updated.
mooki added 116 commits 2026-11-15 23:01:58 +00:00
Was: #643 (#643), branch mac/mvk-push at ca17df3be6 (Sweep3, on main aa95d35f).

Its own commits, squashed:
- fix(macos): storage buffer tables get descriptor sets on MoltenVK (ca17df3be)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #644 (#644), branch mac/mvk-sizes at f08eb70206 (Sweep3, on main aa95d35f).

It was stacked on #643; their changes are the earlier commits here.

Its own commits, squashed:
- fix(macos): programs reading storage buffer lengths get descriptor sets on MoltenVK (f08eb7020)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #645 (#645), branch mac/mvk-rwtex at b8b1ba998a (Sweep3, on main aa95d35f).

It was stacked on #644; their changes are the earlier commits here.

Its own commits, squashed:
- fix(macos): stages with more than 8 read_write textures get descriptor sets on MoltenVK (b8b1ba998)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
fix(vk): use update-after-bind sets past Metal's per-stage limits on MoltenVK
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 4s
CI / Workflow lint (actionlint) (pull_request) Successful in 5s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 5s
Third-party parts / As their notes say (pull_request) Successful in 7s
PR description / Description follows the template (pull_request_target) Successful in 6s
Website / Website on Cloudflare (pull_request_target) Has been skipped
88e914ad4e
Was: #646 (#646), branch mac/mvk-pushlimits at 374c55a031 (Sweep3, on main aa95d35f).

It was stacked on #645; their changes are the earlier commits here.

Its own commits, squashed:
- fix(macos): stages past a Metal function's buffer, texture or sampler table get descriptor sets on MoltenVK (6c9e3c9fa)
- fix(macos): MoltenVK's descriptor sets are update-after-bind layouts, within Vulkan's limits for them (3e7d8d3d3)
- test(vk): recording_admission's device stub has the fixes make_pool now reads (374c55a03)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Every scan down vk_memory.cpp's import table by start (pool_lookup's
covering import and merge plan, bg_drain, prefetch_chunks,
import_in_background, memory_note_gpu_write and memory_guest_imported)
stopped once an import ended more than 1 GiB below its address, on the
belief that no import is larger than that. pool_lookup's own merge escape
leaves an import above 1 GiB over the smaller ones inside it ("left
overlapping"), and the device allows imports up to max_import_size: a scan
stopped at a small import inside a large one, missed the large one, and
the same bytes were imported again, two memories over the same bytes.

import_reach.h counts the live imports by span class; its bound is above
every live span, within twice the largest. imported_add and imported_take,
now the table's only ways in and out, keep the count. A scan stops only
where no import further down can reach its address, so it also stops
sooner than before when the imports are small. The covering-import checks
in pool_lookup and import_in_background look past the last import at or
below the range for the same reason.

Tests: test_import_reach.py runs the actual scans with a 4 GiB import over
a 16 MiB chunk, left by the merge escape (imports are recorded ranges: no
payload, no Vulkan, no game). Its lookup, query, note, drain, background
and prefetch cases fail on main 5e072fc8 and pass here, and a source check
keeps every change to the table in the two helpers. test_import_windows
runs pool_lookup with the helpers; test_mirror_gpu_only names the new
publication point.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
test(vk): the readback refresh fixture runs memory_note_gpu_write with the import table's helpers
All checks were successful
PR description / Description follows the template (pull_request_target) Successful in 4s
e89e33655a
test_parallel_rb_refresh cuts memory_note_gpu_write out of vk_memory.cpp,
whose scan now stops at the live imports' reach: the fixture includes
import_reach.h, cuts live_reach, imported_add and imported_take beside it,
and puts its pool in the table through imported_add. It failed to build
at 11e9ee44 ("use of undeclared identifier 'import_reach'").

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #454 (#454), branch mac/run-all at 264f826a7c (Sweep3, on main aa95d35f).

Its own commits, squashed:
- test: teach the game-free runner about macOS (45c54bc6f)
- test: skip main's new Windows-only guard check on macOS, and undo the SDK's vsnprintf macro in a fixture (264f826a7)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #477 (#477), branch mac/arm64-host at 0f021f29c1 (Sweep3, on main aa95d35f).

Its own commits, squashed:
- fix(runtime): compile host jumps and pause hints on macOS arm64 (0f021f29c)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #478 (#478), branch mac/guest-memory at dfb71ec850 (Sweep3, on main aa95d35f).

Its own commits, squashed:
- fix(runtime): preserve guest pages when discarding on macOS (b668404c8)
- fix(runtime): retain guest-page rounding in Darwin memory wrappers (e9c77d9f3)
- test(runtime): cut main's int hos_commit in the Darwin guest-memory test (7e737ce0f)
- test(runtime): follow main's HLE call counts in the Darwin guest-memory fixture (dfb71ec85)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #436 (#436), branch mac/fault-contexts at bccfd1c2e9 (Sweep3, on main aa95d35f).

Its own commits, squashed:
- fix(runtime): translate macOS fault contexts on both CPU routes (08940fb3d)
- test(runtime): keep Darwin fault checks native by default (7d7f99dcb)
- test(runtime): classify the fault bridge's fatal _exit in main's exit inventory (bccfd1c2e)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #437 (#437), branch mac/waits at beb8a2881a (Sweep3, on main aa95d35f).

Its own commits, squashed:
- fix(runtime): port Win32 waits and deadlines to macOS (2f05d007f)
- test(runtime): link Darwin waits into the pointer fixture (ef081688d)
- fix(macos): share address wait state through the executable (186a461c5)
- docs(runtime): describe the executable-owned macOS address-wait state (beb8a2881)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #438 (#438), branch mac/vk-admission at 681e37081d (Sweep3, on main aa95d35f).

Its own commits, squashed:
- feat(vk): add macOS Vulkan loader and device admission (6f34d00bc)
- test(vk): use semantic admission contracts (fdd161190)
- test(vk): follow main's LoadLibraryA and float-add choice in the admission fixture (3e088644f)
- test(vk): pin the admission ABI at main's version 23 and macOS 24 (4f4ca3c73)
- fix(macos): a window without Vulkan extensions ends as a clean exit, as main's exit inventory asks (681e37081)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #490 (#490), branch mac/darwin-host at 162a39dcd3 (Sweep3, on main aa95d35f).

It was stacked on #436, #437, #438, #454, #477, #478; their changes are the earlier commits here.

Its own commits, squashed:
- feat(macos): complete Darwin host lifecycle and diagnostics (71a9ed0bb)
- fix(macos): integrate profile consumers and joined-thread shutdown (f420761ab)
- docs(macos): describe Darwin profile symbol loading (04e40191a)
- test(macos): integration fix: cut the tagged HThread in the waits fixture (9c18e64c4)
- test(macos): integration fix: stub the kept startup in the display fixture (5f8d511e6)
- test(macos): integration fix: prof symbols run on macOS, not a skip (a1e73d31e)
- test(macos): the memory-notice fixture runs the Darwin query (f4d7aaf76)
- fix(macos): a failed swap query still shows the low-RAM notice (28ed288a2)
- test(macos): the Darwin LoadLibraryA keeps dlerror()'s text for hos_load_error (52faf1d3d)
- fix(macos): integration fix: main's process affinity for new threads is Linux-only (61ec2411b)
- fix(macos): the POSIX main's end after the game's thread marks the clean end, as main's exit inventory asks (162a39dcd)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #453 (#453), branch mac/build-flags at 8ca4bff7a4 (Sweep3, on main aa95d35f).

Its own commits, squashed:
- build(macos): discover dual-architecture toolchains and form Mach-O commands (499e3853a)
- test(macos): default real link fixtures to the process architecture (f6f6f042c)
- test(macos): isolate synthetic command paths from the test host (7c846ae91)
- build(macos): keep third_party/a64-kit as it is; nx2/darwin_toolchain.py makes its commands Mach-O (88054c966)
- build(macos): follow main's one-way renderer build and CPU target in the moved build code (a5b02633d)
- test(macos): the frozen Windows/Linux build arrays are main e090cc48's (c3009e01c)
- test: main's third-party objects test reads build.py with this PR's macOS names (8ca4bff7a)

Rebased onto main 7bacf846 (conflicts with #857 and #577, by hand): nx2/build.py keeps main's host-source line verbatim
(tests/test_no_webgpu.py matches it) with Darwin in its own clause before it; the WebGPU renderer job and have_wgpu go
(#577); executable_link loses its wgpu parameter and wgpu-native's import library and takes exe_resources() (#857) as
resources; nx2/make_game.py keeps main's BESIDE with this commit's DARWIN import, and the icon line takes #857's form with
(LINUX or DARWIN); tests/test_macos_build_flags.py and tests/build_flags_main.json drop wgpu-native the same way.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #479 (#479), branch mac/build-complete at 1bd269c7e2 (Sweep3, on main aa95d35f).

It was stacked on #437, #453; their changes are the earlier commits here.

Its own commits, squashed:
- build(macos): complete strict standalone dependency packaging (9424b4886)
- fix(macos): bind SDL3, imports and archive members to their real formats (8ad0e3265)
- fix(macos): keep the lazy-bind library ordinal across DONE (48f6ec02b)
- build(macos): take the architecture and SDK from darwin_toolchain when packaging (5ce85548c)
- build(macos): no prebuilt renderer on macOS either, as main has none (1bd269c7e)

Rebased onto main 7bacf846 (conflicts with #577, by hand): nx2/make_game.py keeps main's removal of an old wgpu_native.dll
and this commit's macOS packaging after it; docs/development.md keeps this commit's host/ and gpu/vk/ rows and main's
gpu/render/ row (the WebGPU renderer is built no more).

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #455 (#455), branch mac/mem-gate at 82c2e10341 (Sweep3, on main aa95d35f).

Its own commits, squashed:
- fix(builder): account for available memory and compiler children on macOS (8f8e03b7f)
- fix(builder): avoid stale Darwin available-memory snapshots (5240e431a)
- fix(builder): keep Darwin RSS behind the shared tree backend (82c2e1034)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #456 (#456), branch mac/control-sockets at fc2f104050 (Sweep3, on main aa95d35f).

Its own commits, squashed:
- fix(runtime): support control bridge Unix sockets on macOS (5fc3fe390)
- test(control): link the bridge's macOS socket helpers into test_oot_state_tap's fixture (fc2f10405)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #457 (#457), branch mac/control-quit at fe3e8c9178 (Sweep3, on main aa95d35f).

It was stacked on #456; their changes are the earlier commits here.

Its own commits, squashed:
- test(control): quit's parent waits for its bridge to listen, and a failed check ends the bridge it forked (fe3e8c917)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #476 (#476), branch mac/cache-files at 7e561fbb53 (Sweep3, on main aa95d35f).

Its own commits, squashed:
- fix(vk): preserve cache file reservations on macOS (7e561fbb5)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #480 (#480), branch mac/guest-16k at 657b780359 (Sweep3, on main aa95d35f).

It was stacked on #436, #478; their changes are the earlier commits here.

Merged with the topic's earlier commits by hand where they met (Consolidate-files/hand-resolutions.md).

Its own commits, squashed:
- fix(macos): serialize guest backing and native-page watch lifetimes (d7d999b92)
- fix(macos): retain pending watch faults across protection changes (a6a3e9e98)
- fix(macos): make the guest-memory changes Apple-only; Windows and Linux keep main's code (126d7bd67)
- docs(macos): describe the guest window's one owner, import pins and native-page watches (657b78035)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #492 (#492), branch mac/renderer-compile at 59f750aa38 (Sweep3, on main aa95d35f).

Its own commits, squashed:
- fix(macos): the renderer's last two files compile on Darwin (7ee5fd584)
- fix(macos): the debug tools are compiled on Darwin too (82b2d6606)
- test(macos): the debug tools check reads hos_oot_player_seen's body too (59f750aa3)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #511 (#511), branch mac/crash-records at c4d95017aa (Sweep3, on main aa95d35f).

It was stacked on #436; their changes are the earlier commits here.

Its own commits, squashed:
- fix(runtime): take the macOS report run id from getentropy (d3e86ddd7)
- fix(runtime): read crash-record memory and modules without /proc on macOS (aa039e142)
- test(runtime): build the crash-record fixture on macOS (adebf9dbb)
- test(runtime): link the macOS fault bridge into the crash-record fixture (c4d95017a)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #516 (#516), branch mac/longshot-ctl-darwin at 3b9d3cfa2a (Sweep3, on main aa95d35f).

Its own commits, squashed:
- fix(control): tell macOS processes apart by their sysctl start time (56f4ca876)
- test(control): compare launch's data folder with the resolved run folder (3b9d3cfa2)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #491 (#491), branch mac/renderer-correctness at 695f6859dc (Sweep3, on main aa95d35f).

It was stacked on #438, #480; their changes are the earlier commits here.

Its own commits, squashed:
- fix(macos): pin renderer imports through final resource ownership (db82a0f23)
- test(macos): cut the non-Apple Pool and import route in three more fixtures (6cee76eb1)
- fix(vk): drain the recorder before startup rollback destroys the allocator (18c05be52)
- test(macos): follow main's #324 and #250 in the Darwin renderer fixture (c099f5da6)
- test(vk): follow the moved Pool in test_mirror_gpu_only's cut (165bf7e61)
- fix(macos): the import pin callbacks are macOS host API version 25 (fa691b55b)
- fix(macos): vk_memory.cpp compiles on macOS: #324's evicted_pools declaration is not Apple's (695f6859d)

Rebased onto main 7bacf846 (conflicts with #223, by hand): gpu/vk/vk_memory.cpp declares main's evicted_import_bytes after
this commit's macOS evicted_pools #endif, and imports_give_back keeps main's accounting line before this commit's
destroy_import(p) (which frees the pool's pieces as main's lines did).

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #642 (#642), branch mac/gpu-budget at 09978824a0 (Sweep3, on main aa95d35f).

Its own commits, squashed:
- feat(vk): read the Mac's system memory for the renderer (gpu/vk/system_memory.h) (ba1952096)
- fix(macos): on unified memory the GPU's allowance is what the Mac's RAM leaves, not Metal's working set (632636ee0)
- fix(macos): vk_work.h stays vk_vma.cpp's last include (0e63a1dc1)
- fix(macos): the unified budget reads the system's memory at its first ask (5240eade7)
- docs(macos): RX_VK_UNIFIED_BUDGET in the switch table (09978824a)

Rebased onto main 7bacf846 (conflict with #223, by hand): texture_frame's staging arenas go when kept + size passes this
commit's keep_now, or main's stale time (5 s under Linux memory pressure) passes, or main's Linux pressure begins; on macOS
main's Linux pressure never turns on, and keep_now is keep off macOS.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #653 (#653), branch mac/metal-cache at db50cf3d26 (Sweep3, on main aa95d35f).

It was stacked on #438; their changes are the earlier commits here.

Its own commits, squashed:
- feat(macos): Metal's shader cache in a folder the caller names (db50cf3d2)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #654 (#654), branch mac/kosmickrisp at 9d34f9a1c8 (Sweep3, on main aa95d35f).

It was stacked on #438, #479; their changes are the earlier commits here.

Merged with the topic's earlier commits by hand where they met (Consolidate-files/hand-resolutions.md).

Its own commits, squashed:
- feat(macos): ship the Vulkan loader with KosmicKrisp and MoltenVK, chosen at startup (fbd562421)
- test(macos): the driver package fixture takes the architecture and SDK from darwin_toolchain (3472d670c)
- fix(macos): type the driver manifest's ICD record for Pyright (296b5347b)
- fix(macos): MoltenVK is the default Vulkan driver on every macOS (86c017e42)
- test(macos): the display fixture counts longshot_env.txt's loads on Apple only (9d34f9a1c)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
The topic needs it (as the stacks merged it before).

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
The topic needs it (as the stacks merged it before).

Rebased onto main 7bacf846: merges #431's rebased head e89e3365 (the same two commits on 7bacf846); vk_memory.cpp and the two
tests take c1229ac2's resolution, replayed by git merge-file (c1229ac2 over its first parent, onto this merge's first parent): clean.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #647 (#647), branch mac/seg-plan at 52def6832c (Sweep3, on main aa95d35f).

Its own commits, squashed:
- feat(vk): plan where an oversize guest span is cut into import segments (601c00ccd)
- feat(vk): let the segment planner add segments that pay for themselves (52def6832)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #648 (#648), branch mac/seg-shader at 9b73e82942 (Sweep3, on main aa95d35f).

Its own commits, squashed:
- feat(vk): descriptors bound as pieces in the SPIR-V back end and program variants (1f9183c2a)
- fix(vk): MslArrayPtr: no pointer into a storage buffer array is passed to a function (9b73e8294)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #649 (#649), branch mac/texel-codec at c5cbd39d26 (Sweep3, on main aa95d35f).

It was stacked on #648; their changes are the earlier commits here.

Its own commits, squashed:
- feat(vk): texel codecs in the SPIR-V back end and program variants (c5cbd39d2)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #658 (#658), branch mac/renderer-core at f8d4e51ad5 (Sweep3, on main aa95d35f).

It was stacked on #431, #491, #647; their changes are the earlier commits here.

Merged with the topic's earlier commits by hand where they met (Consolidate-files/hand-resolutions.md).

Its own commits, squashed:
- fix(vk): join #431's import table helpers with #491's macOS Pool (a1d08d92a)
- fix(macos): import NOACCESS guest pages and name a missing audio service (e6e92a90d)
- feat(vk): admit an operation's guest buffers before it binds them (alias isolation, macOS) (a27bee681)
- feat(vk): import a span past one device allocation as segments (SegMem, alias isolation) (dd4f13047)
- test(vk): follow the renderer-core merge's moved code in three extractions (6e77a383f)
- fix(vk, macos): admit a parallel batch's uniform updates in order, and keep its own updates out of its handoff (3fbfca08d)
- fix(vk, macos): keep every byte the page table reached mapped when an admission retires imports (616eacb83)
- fix(vk, macos): one view per byte of an Apple spare backing, and no endless retry of a failed view (04e00832b)
- fix(vk, macos): bg_drain publishes no background import over this epoch's retired memory or across a domain (a3913a646)
- fix(vk, macos): admission merges no import past 1 GiB again, so mirror_make can still mirror it (b8d16a20b)
- fix(vk, macos): a segment keeps a crossing import's bytes as leftovers clipped at the cuts, not as whole segments (aab3fd8a6)
- fix(vk, macos): each new import over a retired import's bytes inherits its share of that import's VRAM mirror (73bbb89ad)
- test(vk): the admission fixtures follow main's #250 sparse mirrors (6fa302cce)
- fix(vk, macos): the actor motion's resolver follows #59: a pose read at its draw is not copied (e0941ccc0)
- test(vk): test_split_ub_flush follows flush_ub_updates' end parameter (f8d4e51ad)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #662 (#662), branch mac/seg-contract at 0401eeb237 (Sweep3, on main aa95d35f).

It was stacked on #649, #658; their changes are the earlier commits here.

Its own commits, squashed:
- feat(vk): the segmented consumers' frozen contract (C0) (0401eeb23)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #663 (#663), branch mac/seg-consumers at 5400f1a0b6 (Sweep3, on main aa95d35f).

It was stacked on #645, #662; their changes are the earlier commits here.

Its own commits, squashed:
- feat(vk): texel codecs' views, texel piece views, null-descriptor stand-ins and presence words (TexelDesc, L3) (da741bdb2)
- test(vk): the texel ownership fixture names the case that failed (39d6490dd)
- feat(vk): SegBind's descriptor core, gathers and arena (L1) (7d5d51276)
- fix(vk): a draw reusing its descriptors drops an earlier build's refusal (SegBind) (7104d8324)
- test(vk): SegBind's gathers and notes fixtures, its parts of three checks, and its docs section (31d52778f)
- test(vk): test_set_for_tables reads its cut from --source (4462202ff)
- test(vk): test_mesh_fallback's topology anchor follows draw()'s `plain` (0f743f0b9)
- test(vk): test_set_for_lengths' layout fixture takes SegBind's seg_layout_count and presence_words (3b5f3b477)
- feat(vk): SegXfer, the transfer consumers of a range across a segment's cut (L2) (3200ff464)
- fix(vk): dispatch()'s compute-variant path (#252) names SegBind's pre-seam `plain` (c13540fc5)
- test(vk): the seg_gathers fixture stubs #162's rec::OwnSlot (8089dc409)
- test(vk): SegXfer's fixture and resolver sites follow #59's actor motion (1ab6beb2b)
- test(vk): SegXfer's gpu_write checks follow #329's ordered inline writes (5400f1a0b)

Rebased onto main 7bacf846 (conflicts with #231 and #403, by hand; #403 by the owner's decision: main's generic dummy views
stay on every device without nullDescriptor, the typed stand-ins on Apple only):
- RecordingRes keeps main's FlatMap c1_at (#231) with this commit's arena fields, and draw_begin_recording resets the arena
  and calls main's c1_at.reset().
- make_dummies is main's (#403) unchanged; the stand-ins move to make_stand_ins (Apple), called once beside
  null_storage_make, before make_dummies. NullDummies carries main's generic view[] (dummies stays one object).
- build_descriptors binds a typed stand-in first where they are made, then main's generic view where none is (sampled
  images as main's existing line did; storage images as #403's line does), so nothing is bound VK_NULL_HANDLE without
  nullDescriptor.
- The cut-out fixtures that stub null_storage_make stub make_stand_ins too.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #674 (#674), branch mac/null-shader at b7683077e6 (Sweep3, on main aa95d35f).

It was stacked on #663; their changes are the earlier commits here.

Its own commits, squashed:
- feat(vk): null-descriptor emulation in the SPIR-V back end (NullShader, L4) (71003696f)
- docs(vk): NullShader: image and image buffer arrays share a known gap (17667bea3)
- fix(vk): NullShader: two source-cutting checks the wip commit broke (f53eda6cd)
- fix(vk): MslArrayPtr's NullShader half: a descriptor bound whole calls its loop function, and the loops' CPU runs (b7683077e)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #675 (#675), branch mac/tex-read-order at c5c6a853a8 (Sweep3, on main aa95d35f).

It was stacked on #674; their changes are the earlier commits here.

Its own commits, squashed:
- fix(vk): TexOrder: store each image read in place on MoltenVK (fb51f7807)
- test: test_amd_subgroup_profiles: the MoltenVK driver id in make_profile's stand-in (8d5fc5373)
- fix(vk): TexOrder: an image memory barrier before each image write and atomic on MoltenVK (c5c6a853a)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #676 (#676), branch mac/msl-depth at f8e18c953b (Sweep3, on main aa95d35f).

It was stacked on #675; their changes are the earlier commits here.

Its own commits, squashed:
- fix(macos): MoltenVK's Metal source nests no deeper than 32 forwarded instructions (71d2498c4)
- test(vk): the subgroup profile fixture knows MoltenVK's driver id (f8e18c953)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #686 (#686), branch mac/rosetta-import at 6ec9629e59 (Sweep3, on main aa95d35f).

It was stacked on #658; their changes are the earlier commits here.

Its own commits, squashed:
- fix(macos): Rosetta host imports: whole hardware pages, refused imports asked again only when their backing changes (ae91338ae)
- fix(macos): the backing generation is Apple host API version 26, after #491's import pins at 25 (6ec9629e5)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #692 (#692), branch mac/msl-depth2 at a67e1934ec (Sweep3, on main aa95d35f).

It was stacked on #676; their changes are the earlier commits here.

Its own commits, squashed:
- fix(macos): the nesting bound counts only the reads SPIRV-Cross certainly makes (a67e1934e)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #693 (#693), branch mac/compile-gaps at 5ceed495b2 (Sweep3, on main aa95d35f).

It was stacked on #692; their changes are the earlier commits here.

Its own commits, squashed:
- fix(vk): bound the control-flow nesting of SPIRV-Cross's Metal source on MoltenVK (46b5810a9)
- perf(vk): parse the module in place when the scope bound has nothing to move (5ceed495b)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #694 (#694), branch mac/subgroup-vertex at a3e8a51faf (Sweep3, on main aa95d35f).

It was stacked on #676; their changes are the earlier commits here.

Merged with the topic's earlier commits by hand where they met (Consolidate-files/hand-resolutions.md).

Its own commits, squashed:
- fix(vk): MoltenVK's vertex stages run the guest's warp operations as one-lane warps (a2b3b0578)
- test(vk): test_subgroup_vertex: the base tree's own checks unprinted, and one failure message per cause (e20482fa9)
- test(vk): test_subgroup_vertex: SPIRV-Cross drops a subgroup barrier in a vertex function (a3e8a51fa)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #695 (#695), branch mac/spv-size at 43d1a23420 (Sweep3, on main aa95d35f).

It was stacked on #676; their changes are the earlier commits here.

Its own commits, squashed:
- feat(vk): RX_VK_SPV_PROFILE, what the big SPIR-V modules are made of (3d7b1f5f6)
- docs(vk): spirv_profile.h's store names where the line is printed (ebf1854b4)
- docs(vk): RX_VK_SPV_PROFILE's text names the slow compile line as the precompile hand-off's (43d1a2342)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #696 (#696), branch mac/gm-loop at 231115f14c (Sweep3, on main aa95d35f).

It was stacked on #694, #695; their changes are the earlier commits here.

Merged with the topic's earlier commits by hand where they met (Consolidate-files/hand-resolutions.md).

Its own commits, squashed:
- feat(vk): MoltenVK and KosmicKrisp search storage buffer tables in loops in every global memory fallback (39a40fed6)
- test(vk): gm_loop_ir --gpu: the loop forms first, then the written-out ones, smaller first (99616b7ab)
- test(vk): stub table_loops_on where make_profile is compiled cut out (231115f14)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #697 (#697), branch mac/local-mem-buffer at a526c34c9f (Sweep3, on main aa95d35f).

It was stacked on #696; their changes are the earlier commits here.

Its own commits, squashed:
- feat(vk): MoltenVK zeroes local memory at computed offsets by a loop, not a written-out initializer (a526c34c9)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #698 (#698), branch mac/kk-tex-order at 8a3d7db0ce (Sweep3, on main aa95d35f).

It was stacked on #654, #675; their changes are the earlier commits here.

Its own commits, squashed:
- fix(macos): TexOrder's stored image reads on KosmicKrisp too (27d566b45)
- test(macos): the Apple drivers' check names the fixes this tree makes (8a3d7db0c)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #787 (#787), branch mac/giant-shape at 96b51b55b5 (Sweep3, on main aa95d35f).

It was stacked on #697; their changes are the earlier commits here.

Its own commits, squashed:
- test: giant mesh fallbacks' shape through the real SPIR-V back end (tests/giant_shape_ir.cpp) (96b51b55b)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
The Mac-only part of fix/async-safe-frees-i40 (c151fcea, MvkAsyncFix's F5) that #788 does not carry, because
null_dummies_make (#663, macOS: MoltenVK has no nullDescriptor) exists only on the macOS stack. The stand-in images' clear
waits 5 s for its fence; when that wait ran out, the fence and the command pool were destroyed while the GPU might still be
clearing (a destroyed pool under a pending command buffer). Now a clear submitted and not seen done in 5 s is waited for
without a limit first, as #788 does for the read-back. The clear is still reported as not done in time (the "may read
garbage" line), as before.

tests/test_null_dummies.py: case make-slow-clear (the fixture's fence wait runs out once): one unbounded wait after the 5 s
one, before the fence and the pool are destroyed. Fails before this commit (one wait, none unbounded), passes after, on arm64
and x86_64 under Rosetta.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
In this topic #698 (KosmicKrisp's TexOrder, its Apple drivers' fixture in test_vendor_fixes) meets #694/#696
(SubgroupVertex: make_profile reads dev.subgroup_stages and Shader::Stage) and #697's two switches (GmLoop's
table_loops_on, LocalMemBuffer's local_zero_loop_on), and test_subgroup_vertex's stub meets KosmicKrisp's
VK_DRIVER_ID_MESA_KOSMICKRISP in make_profile. Each member passes at its own Sweep3 head; at the topic's tip the
fixtures did not build. This takes I41's fixes 02b10861 and 560923891's stub line:
- test_subgroup_vertex: the KosmicKrisp driver constant (28, the Vulkan headers' value);
- test_vendor_fixes' Apple drivers' fixture: subgroup_stages (all stages), stage.h, and table_loops_on and
  local_zero_loop_on stubs; its columns are unchanged.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
(cherry picked from commit 02b108611 and the local_zero_loop_on line of 560923891)
The port 55cfa887 (a stand-in clear not done in 5 s is waited for, without a limit, before its fence and command pool are
destroyed) put two lines in null_dummies_make that Windows and Linux compiled too, though they never run there:
null_dummies_make returns at once off Apple (null_dummies_on() is false: kApple). The two lines now sit inside
#if defined(__APPLE__), the file's gate for its other macOS-only lines, so Windows and Linux compile none of the port:
vk_texture.cpp off Apple (unifdef -U__APPLE__) is the same as at the port's parent 1bf322f4, and on macOS the code is
55cfa887's.

tests/test_null_dummies.py cuts null_dummies_make with the gate and builds it on macOS, where __APPLE__ is defined; its
make-slow-clear case is unchanged.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #650 (#650), branch mac/prep-fast at 6bc44ad83b (Sweep3, on main aa95d35f).

Merged with the topic's earlier commits by hand where they met (Consolidate-files/hand-resolutions.md).

Its own commits, squashed:
- fix(macos): the shader preparation runs on every usable CPU on macOS (928d6afc0)
- fix(macos): a pipeline cache per preparation worker on MoltenVK (71ddd7247)
- fix(macos): the worker caches make no Vulkan call from a header (7b957f8ec)
- fix(macos): MoltenVK starts with an empty pipeline cache and writes none (4c8c82548)
- fix(macos): the worker caches follow main's fetch lock (#190) and Intel's gate (#252) (6bc44ad83)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #651 (#651), branch mac/thread-stack at a7c1f493de (Sweep3, on main aa95d35f).

Its own commits, squashed:
- fix(vk, macos): the renderer's threads start with a 16 MiB stack, not macOS's 512 KiB (16f8f3d2a)
- test(macos): one overflow message from thread_stack_test, however many threads overflow at once (b355d677f)
- test: the checks that compile renderer code with its threads see thread_stack.h (a7c1f493d)

Rebased onto main 7bacf846 (include conflicts with #223 and #769): vk_memory.cpp keeps main's linux_pressure.h and this
commit's thread_stack.h; vk_replay.cpp keeps main's hold_gpu.h and this commit's thread_stack.h.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #652 (#652), branch mac/precompile-stall at ba5aa17684 (Sweep3, on main aa95d35f).

It was stacked on #650, #651; their changes are the earlier commits here.

Merged with the topic's earlier commits by hand where they met (Consolidate-files/hand-resolutions.md).

Its own commits, squashed:
- fix(vk): MoltenVK: the precompile goes on behind the game; slow compiles named; a failed compile tried once more (5ceb62a44)
- test(vk): test_precompile_handoff: a tree without the change says each missing piece (576970be4)
- docs: RX_VK_PRECOMPILE_STALL_S, RX_VK_COMPILER_SERVICE and RX_VK_SLOW_COMPILE_S (3c8381113)
- fix(vk): name a graphics compile at its precompile callers, not inside build_graphics (fe6efa98d)
- fix(vk): the precompile hand-off on main's Intel gate and quick builds (#252), fetch lock (#190) and game folder (#321) (ba5aa1768)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #664 (#664), branch mac/warm-handoff at 1f7065181d (Sweep3, on main aa95d35f).

It was stacked on #652; their changes are the earlier commits here.

Merged with the topic's earlier commits by hand where they met (Consolidate-files/hand-resolutions.md).

Its own commits, squashed:
- fix(vk): under compiler_service the preparation leaves the compute pipelines to the precompile (22e75176e)
- fix(vk): at most four giant compiles at once in the precompile under compiler_service (748c4970f)
- docs: RX_VK_GIANT_COMPILES and RX_VK_GIANT_WORDS; the preparation's compute pipelines under compiler_service (225b7b0be)
- fix(vk): giant compiles never hold every worker of a phase (23d8d276b)
- test(vk): test_warm_handoff follows main's warm and dispatch (#252, #190) (1f7065181)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #665 (#665), branch mac/title-stall at a7e966ec87 (Sweep3, on main aa95d35f).

It was stacked on #664; their changes are the earlier commits here.

Merged with the topic's earlier commits by hand where they met (Consolidate-files/hand-resolutions.md).

Its own commits, squashed:
- fix(vk): behind the game no giant compile starts before the first frame; the precompile's giants and its work behind the game below the game's QoS class (1e92c87bb)
- docs: RX_VK_GIANT_HOLD_PRESENTS, RX_VK_GIANT_HOLD_S and RX_VK_COMPILE_QOS (5fb67e4fc)
- fix(vk): a giant compile that failed is tried once more alone, not at once among the other giants (a7e966ec8)

Rebased onto main 7bacf846 (include conflict with main's glibc <malloc.h>): vk_draw.cpp keeps main's glibc block and this
commit's Apple <pthread/qos.h> block, each in its own #if.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #666 (#666), branch mac/loading-stall at 91b67ad468 (Sweep3, on main aa95d35f).

It was stacked on #665; their changes are the earlier commits here.

Merged with the topic's earlier commits by hand where they met (Consolidate-files/hand-resolutions.md).

Its own commits, squashed:
- fix(vk): a dispatch's compute pipeline that MoltenVK's compiler service failed is built, not left out for good (1cb6be613)
- test: test_loading_stall: a tree without the build's retry is a failure said, not a stop (2869b762e)
- perf(vk): RX_VK_SKIP_LOG off works out nothing for a dispatch left out (f9ca934d8)
- fix(vk): a dispatch's build lets play's want go by its own scope, its failed() as it was (daf95bfb7)
- fix(vk): one place, one count and one wording for a failed compile's tries alone (324b0f0fe)
- fix(vk): the dispatch's want and LoadingStall's checks follow main's build (#252) (f0b82bc57)
- test(vk): test_intel_quick_compute reads the dispatch's build with the compile board's capture (91b67ad46)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #667 (#667), branch mac/metal-cache2 at bf988f6226 (Sweep3, on main aa95d35f).

It was stacked on #653, #666; their changes are the earlier commits here.

Its own commits, squashed:
- feat(macos): MoltenVK's pipelines kept in Metal binary archives (6cdd4ddb0)
- fix(macos): the binary archives' state outlives the process's exit (69d3197c6)
- test(macos): test_metal_archive: no -pthread on Windows (eef27adbc)
- fix(macos): Metal binary archives saved once each, by one gated saver, with Metal's staging removed (584acb7a8)
- fix(macos): compile_board has external linkage, for the Metal archive saver in vk_main.cpp (bf988f622)

Comment reworded here (gpu/vk/metal_archive.h's Why, lines 5-10): it states what the runs observed of Metal's
shader cache and no longer cites how Apple's library works.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #669 (#669), branch mac/giant-mem-gate at 143345156d (Sweep3, on main aa95d35f).

It was stacked on #642, #666; their changes are the earlier commits here.

Its own commits, squashed:
- fix(vk): behind the game, giant compiles wait for memory; a lost device on the Mac is said as one (415eb9a45)
- docs: RX_VK_GIANT_ROOM_MB in the switch table (cb5eef04c)
- fix(macos): the lost wait's line and end on the Mac only; vk_replay.cpp as it was elsewhere (143345156)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #681 (#681), branch mac/metal-scratch at e0400e839c (Sweep3, on main aa95d35f).

It was stacked on #663; their changes are the earlier commits here.

Merged with the topic's earlier commits by hand where they met (Consolidate-files/hand-resolutions.md).

Its own commits, squashed:
- diag(vk): RX_VK_LMEM_LOG names each module's private memory and each pipeline's first bind (0f7820dc3)
- test: the excerpt fixtures know RX_VK_LMEM_LOG's hooks (83ae4962d)
- fix(vk): RX_VK_LMEM_LOG on main's dispatch and program cache: the bound pipeline named, the notes beside array_length (6f4512064)
- fix(macos): RX_VK_LMEM_LOG logs on macOS only (e0400e839)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #784 (#784), branch mac/giant-compile-2 at 99e43bd2f3 (Sweep3, on main aa95d35f).

It was stacked on #669, #681; their changes are the earlier commits here.

Its own commits, squashed:
- fix(vk): SegBind's left-out dispatches named, and the precompile's checks read the renderer's dispatch names, after #669 met #681 (05ab99e91)
- test: test_private_memory looks for note_private_memory after a stage's words, as the program cache notes them once #669 met #681 (c7cca440f)
- fix(vk): heavy compiles run alone under Metal's compiler service; the first giant behind the game no longer waits for 16 GB (8b4538f58)
- fix(vk): the local memory weight lives in private_memory.h, so vk_progcache.cpp's cut-out fixtures build (f4be3d899)
- docs(vk): heavy_weight's comment says what probe GC-02 found (9a4f8a6d0)
- docs: RX_VK_GIANT_ROOM_MB's row says the first giant behind the game starts unless the pressure is critical (a70cb0f37)
- fix(vk): the local memory weight is noted on macOS only, where the precompile reads it (99e43bd2f)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #785 (#785), branch mac/kk-compiler-service at 588d5f3851 (Sweep3, on main aa95d35f).

It was stacked on #665; their changes are the earlier commits here.

Its own commits, squashed:
- fix(macos): KosmicKrisp's compiles go through the compiler service's precompile, as MoltenVK's do (588d5f385)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #786 (#786), branch mac/windowed-metal-cache at 976bb0ac6d (Sweep3, on main aa95d35f).

It was stacked on #654, #667, #686; their changes are the earlier commits here.

Merged with the topic's earlier commits by hand where they met (Consolidate-files/hand-resolutions.md).

Its own commits, squashed:
- fix(macos): Metal's shader cache folder asked at the host's start, before SDL's window (42ae6d37d)
- fix(macos): the Metal cache check is Apple host API 27, after the Rosetta imports' backing generation at 26 (976bb0ac6)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Run 36 (I40) began one of its eight heavy compiles in a 15-minute hold. Play's dispatch asked for and
began compute 44511d69 (126,010 SPIR-V words, not heavy) at the load into play; it takes about 15
minutes (889 s in run 25, 965.6 s in run 34, the only runs that held it that long), and while it was
wanted and in flight giant-compile-2's alone rule held every heavy compile back (Board::holds, a giant
of play's on the board), and play's want held the 204 deferred giants back too. A run of the
precompile's that never ended would have stopped the whole precompile behind the game (the drain).

Now a compile in flight for RX_VK_STALE_COMPILE_S (240 s; 0: never, as before) no longer counts,
unless it is heavy: a run of the precompile's (by its first item, from when next() gave it), play's
giant compile (Span, from play_begin) and a compile play waits for (by its program, from want). A
heavy compile still never begins beside another heavy one, play's included whatever its age (play's
compile is heavy by the precompile's measure: heavy_program), nor while memory refuses or the hold
lasts; a young compile still keeps it back until it ends. Tries alone keep their rule. The begin line
says what a heavy compile began beside. 240 s: of the 234 non-heavy compiles of 10 s or more that ended
in runs 32 and 34-36 and I39's eight, all but three took at most 182.7 s, one 429.8 s.

MoltenVK and KosmicKrisp only (compiler_service); every other driver as before.
reports/2026-11-15-giant-starve.md.

Ported onto topic/precompile-metal (main aa95d35f's dispatch build, #252): there the build's want is its
first line, ahead of Intel's on_worker returns, and its serial push passes true; the want names its
program at that first line and at the push, as on I40, and test_loading_stall.py checks both.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
(cherry picked from commit 5292596d69ccf321d0d12f73e39e65753f7ca2be)
Compute 44511d69 (126,010 SPIR-V words, a giant but not heavy) takes about 15 minutes (889 s in run 25,
965.6 s in run 34). In every run read (runs 32 and 34-36, I39's eight, E8a) the precompile claimed it in
its last minutes, among the largest computes or last of the slow list, with four giants in flight: it was
deferred at the giant bound, still deferred at the hand-off, and play's dispatch began it 43-65 s after
the hand-off, at the load into play. Its dispatches were left out for about the first 15 minutes of play
in every start, and no arm64 run held it that long, so Metal's cache never had it.

Now the compute and mesh fallback programs the slow list says took RX_VK_SLOW_FIRST_S (240 s; 0: none)
or more, none heavy, go first in the precompile's order, the longest first, at most the giant limit less
one (slow_first): each compiles beside the rest from the start, at the thread's own QoS class as play's
dispatch asks. Before the game each is a giant like any other: the bound stays four. At the hand-off the
ones still in flight are handed to play (Giants::hand_over): behind the game they keep no place of the
limit and the memory gate does not count them (Giants::counted), as play's own compile of the program was
not counted in every run before; a try alone still waits for them and, while young, a heavy compile
(GiantStarve's rule). Not handed, the slow one would keep every other giant and heavy compile back until
it ends whenever the memory is short of a room, which it was behind the game in runs 32 and 34-36 and E8a.
A first one begun after the hand-off is never handed. behind_worker leaves a run before giving its place
back, and its try alone names its run (solo_ask(at)), so a handed run leaves the counts exactly once.

MoltenVK and KosmicKrisp only (compiler_service); every other driver as before.
reports/2026-11-15-slow-first.md.

Ported onto topic/precompile-metal after giant-starve's port: docs/development.md's RX_VK_COMPILE_QOS row as this
commit words it, followed by the topic's RX_VK_GIANT_ROOM_MB row (#784), which I40 did not have there; every other
change line for line as 40a86bae made it on 5292596d.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
(cherry picked from commit 40a86baedd6ba1651dc2e62e74af64eccbc18e5c)
The header's comment, two of its code comments and three comments in test_metal_archive.py's fixture
named Apple's internal libraries, functions and return codes (libCoreFSCache, its 0xd3, the archiver's
and packer's internals). They came from reading Apple's binaries, which is not ours to do; they are
reworded to what runs and public notes show (reports/2026-11-15-metal-cache-cap.md):
- the cache: two files capped at about 1 GiB each (public notes), unchanged in size since run #17,
  written by a warm start within a minute of the hand-off at the latest, nothing compiled later kept;
- the staging: one gpuarchiver-* folder per archive, left behind after a save (run #21: 1,042, 12 GB),
  named by the archive and removed by the saver;
- render pipelines without a fragment function: archives of their own, so that a save Metal refuses
  with "expecting 'fragment' stage in pipeline no. N" (run #21) costs none of the others.
No code change: both files are line for line the same without their // comments.

Ported onto topic/precompile-metal: the header's Why (lines 5-10), which #667's commit here already reworded, now
reads as this commit words it; both files are byte for byte 63fc3d2c's.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
(cherry picked from commit 63fc3d2cecd006a97726f9451c8bdfc4176e83a6)
The giant-starve port (310fbb8e) moved play's want into main's dispatch build (#252), the lambda
"auto build = [job, on_worker, made_how, board_on]", and changed test_loading_stall.py's cut to it;
test_giant_alone.py still cut I40's "auto build = [job, board_on]", which the topic does not have, and
failed with "a function not found". Its cut now names main's build; the checks on what the build holds
(play's giant compile begun, heavy or not, as it begins) are unchanged.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
In this topic #664's check (test_warm_handoff) meets #695's RX_VK_SPV_PROFILE line in seed_compute (topic 4), as
Integration 25 met them; the check failed at the topic's tip (it passes at #664's Sweep3 head), so this takes I41's fix:

A second semantic merge fix for Integration 25. test_warm_handoff
(WarmHandoff, acd3a71a) checks in vk_shader.cpp's seed_compute that a
kept variant is saved (program_cache_save) on the line before the warm
is given it, by matching the two lines verbatim. SpvSize (1a50b01b)
adds spv_profile_lines before the save on that line and a comment after
it, so on the merged tree the check failed though the order is
unchanged. Each branch passes alone. The check now strips comments and
asks for a line ending in the save, followed by `if (made) made(*t.p);`
(checked: it still fails with the two lines swapped or without the
save).

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
(cherry picked from commit 1cbb594a6ab716a864ef54b327339470f33a0f8b)
The chain's resolution of #650 (tests/test_vendor_fixes.py: its pipeline-cache check placed whole, before the
Apple drivers' check that #698 added in topic 4, hand-resolutions.md) brought #650's own end of the file with it:
"if __name__ == '__main__': main()" ran before check_apple_drivers was defined, and the test failed with a
NameError at the topic's tip (it passes at #650's and #785's Sweep3 heads). That first call is removed; the
file's own call at its end runs every check, as on I41 78ec1c47.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Run N3 (2026-11-15, macOS 26.7.1, MoltenVK) never reached Metal's compiler service: 17,946 "Unable to reach
MTLCompilerService … Connection init failed at lookup" lines, every compile failing within milliseconds. LS
read each failure as the program's own: it spent every try alone in about a second, gave 7,932 compute
pipelines up before the game started, and a play build that failed was failed for the session.

precompile_handoff.h ServiceReach judges the service out of reach from the compiles' own results: 8 in a row
(RX_VK_SERVICE_BURST) failing in under 250 ms each (RX_VK_SERVICE_FAST_MS), nothing made between. Then no
compile goes to it but one probe at a time, after 1 s and then twice as long each time (30 s at most); a
compile made, or one that failed slower (the service answered), says it is back.

vk_draw.cpp create_watched asks it before each compile under compiler_service. Out of reach, a compile on the
precompile's workers or the tries alone's thread (service_waits) waits, and the precompile's wait still hands
the game on once nothing has finished for the stall time; on any other thread (the preparation's workers,
play's job workers, the replay) it is not asked (-78), so nothing the title waits for hangs on the service,
and the caller is told (service_skipped). A failure while out of reach is not compiled once more
at once. The tries alone that failed meanwhile are given back (Board::alone_refund); play's compute build and
its retry alone leave the program to be asked for again at its next dispatch instead of failed; a graphics
pipeline's full build is built again once the service answers (graphics_rebuild through service_defer), its
entry staying ready so that no draw waits for the service. The log says the loss and the recovery.

Every other driver, and MoltenVK with the service answering, as before. A run of SPIR-V to MSL conversion
failures looks the same: the probe after 1 s is then made, and the pause has cost that second.

tests/service_reach_test.cpp and tests/test_service_reach.py: the class, Board::alone_refund and the wiring;
tests/test_precompile_handoff.py's compile_again fixture now runs vk_draw.cpp's own service_reach,
service_defer and service_noted with create_watched against the made-up driver's service out of reach and
back. docs/development.md: the two knobs.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
(cherry picked from commit 5f91a8f7c30b074148deba6806e3057377b73052)
Was: #677 (#677), branch mac/mode-census at d2fd7a90ff (Sweep3, on main aa95d35f).

It was stacked on #663; their changes are the earlier commits here.

Merged with the topic's earlier commits by hand where they met (Consolidate-files/hand-resolutions.md).

Its own commits, squashed:
- feat(vk): count polygon modes and restart-off strip draws on Apple, log-only (d2fd7a90f)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #678 (#678), branch mac/mvk-temp at 989a6423d9 (Sweep3, on main aa95d35f).

It was stacked on #677; their changes are the earlier commits here.

Merged with the topic's earlier commits by hand where they met (Consolidate-files/hand-resolutions.md).

Its own commits, squashed:
- fix(macos): bind a direct draw's 8-bit indices with their size on MoltenVK (ca6b27fdd)
- docs(macos): RX_VK_INDEX8_SIZE in the switch table (989a6423d)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #679 (#679), branch mac/count-draws at 2028d598e6 (Sweep3, on main aa95d35f).

It was stacked on #677; their changes are the earlier commits here.

Merged with the topic's earlier commits by hand where they met (Consolidate-files/hand-resolutions.md).

Its own commits, squashed:
- fix(macos): draw count draws through a record rewrite where the device has no drawIndirectCount (4d9de1004)
- fix(macos): the count draw report in its own block; SegBind's fixture cuts the rewrite (ce7388bf0)
- fix(macos): buffer updates copied from the recording's stream on MoltenVK (574597e08)
- fix(macos): the count-draw rewrite on macOS only; Windows and Linux give count draws to the driver as before (791fe3a75)
- docs(macos): RX_VK_COUNT_REWRITE in the switch table (e4a7ab285)
- test(vk): test_inline_write_order (main's, #329) has gpu_write's cmd_update_buffer (2028d598e)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #680 (#680), branch mac/drawid-direct at 6c0204eb98 (Sweep3, on main aa95d35f).

It was stacked on #679; their changes are the earlier commits here.

Merged with the topic's earlier commits by hand where they met (Consolidate-files/hand-resolutions.md).

Its own commits, squashed:
- fix(macos): direct draws that read the draw index drawn as one indirect record on MoltenVK (4876f2615)
- fix(macos): tessellated direct draws reading the draw index counted, not logged as errors (32a83be13)
- test(macos): the three recording fixtures stand in stream_usage (6c0204eb9)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #691 (#691), branch mac/moltenvk-main at ebd6b127e2 (Sweep3, on main aa95d35f).

It was stacked on #654, #679; their changes are the earlier commits here.

Merged with the topic's earlier commits by hand where they met (Consolidate-files/hand-resolutions.md).

Its own commits, squashed:
- docs(macos): a MoltenVK built from main as the MoltenVK input (546102abe)
- docs(macos): MoltenVK main 5189f8de with the argbuf-slots patch as the recommended MoltenVK input, and how to build it (ebd6b127e)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #701 (#701), branch mac/fan-key at cd1ce0b214 (Sweep3, on main aa95d35f).

It was stacked on #680; their changes are the earlier commits here.

Merged with the topic's earlier commits by hand where they met (Consolidate-files/hand-resolutions.md).

Its own commits, squashed:
- feat(macos): count fans against their pipelines' static topology on MoltenVK, log-only (773588160)
- fix(macos): fans keyed apart from the other triangle topologies on MoltenVK (cd1ce0b21)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #702 (#702), branch mac/fan-indirect at d7878c9d1a (Sweep3, on main aa95d35f).

It was stacked on #701; their changes are the earlier commits here.

Merged with the topic's earlier commits by hand where they met (Consolidate-files/hand-resolutions.md).

Its own commits, squashed:
- feat(macos): count indirect fans and their records on MoltenVK, log-only (927ed3de1)
- fix(macos): an indirect fan of more than one record drawn a call a record on MoltenVK (3a743b80f)
- test(macos): the indirect fans' census checked right after FanKey's, not as draw()'s last statement (62a089ad7)
- test(macos): the segment gathers' fixture stands in FanIndirect's way and split (d7878c9d1)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #703 (#703), branch mac/provoking-first at 73d4bc9bd4 (Sweep3, on main aa95d35f).

It was stacked on #701; their changes are the earlier commits here.

Merged with the topic's earlier commits by hand where they met (Consolidate-files/hand-resolutions.md).

Its own commits, squashed:
- feat(macos): count the draws that depend on the provoking vertex where the device has no provokingVertexLast (8276aa94d)
- fix(macos): direct draws that depend on the provoking vertex drawn with each primitive's last vertex first, without provokingVertexLast (ac8416c59)
- fix(macos): adjacency draws that depend on the provoking vertex drawn as plain lists with each primitive's last vertex first (1977f19f5)
- fix(macos): the mesh fallback's draws that depend on the provoking vertex drawn with each primitive's last corner first (6493717b6)
- fix(macos): lines that depend on the provoking vertex counted only, not reversed (e702fd96e)
- fix(macos): a converted draw's list written into the stream of the recording it is drawn in (4f9891106)
- test(macos): draw()'s fixtures stand in ProvokingFirst's list and count its index binds (e42bf6e87)
- test(macos): test_fan_key reads draw()'s count lines with ProvokingFirst's count on them (531fd13ec)
- test(macos): a converted fan is drawn with a pipeline built as a list under FanKey's key (523d0696e)
- fix(macos): the provoking-vertex count and lists on macOS only; Windows and Linux record as before (73d4bc9bd)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Hand resolution on topic/draw-path, where #702 (FanIndirect) met #703 (ProvokingFirst), siblings on #701 that only this topic
combines. test_fan_indirect (#702) cuts draw()'s indirect block up to "} else if (d.indexed) {"; #703 puts its own branch,
"} else if (pv.made) {" (the list written into the stream and drawn as an indexed draw), between the two, so the cut took it in and
the fixture no longer built (pv, ProvokingWrite, game_topo, drawid_direct undeclared). The cut now ends at draw()'s next branch,
whichever it is, as Integration 37's eb4d02046 has it (its tests/test_fan_indirect.py line only). The check keeps what it requires;
no source changes.

test_fan_indirect: failing at 5efbe9d8 on arm64 and x86_64, passing with this commit; passing at #702's Sweep3 head d7878c9d.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Hand resolution on topic/draw-path. #701's resolution (chain commit 21e6ec79) placed draw_fan_census_report after #678's
draw_index8_report and dropped the closing } of draw_index8_report, so gpu/vk/vk_draw.cpp stopped compiling from there ("function
definition is not allowed here" at draw_fan_census_report, then every later definition), on arm64 and x86_64, at every commit from
21e6ec79 to this one. The } goes back after the report's logf, as Integration 41 (78ec1c47, vk_draw.cpp 5087) has it, without
#782's widen8_report line (topic mac-perf). No other change.

Found by the whole-file compile of vk_draw.cpp at this topic's tip and at the topics on it.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
#705 restacked on topic/draw-path (the topic that carries #679, which it was stacked on): its commits at 5fa122654c (Sweep3, on main aa95d35f), squashed into one because the topic's later commits meet them. Every platform. Its own commits:
- feat(vk): count quad draws, and the indirect ones left out (log-only) (08878e8c7)
- fix(vk): draw indirect quad draws, with and without a count, on every driver (30c4461d3)
- fix(vk): an indexed quad expansion's workgroup bound saturates (5fa122654)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
#707 restacked on topic/draw-path (the topic that carries #679, which it was stacked on): its commits at b41a03a9ac (Sweep3, on main aa95d35f), squashed into one because the topic's later commits meet them. Every platform. Its own commits:
- feat(vk): count mesh draws by kind and what the mesh fallback cuts (log-only) (435c47d47)
- feat(vk): draw mesh count draws on the compute fallback (092afd495)
- fix(vk): the mesh fallback's records area grows on demand (17cace138)
- test(vk): six fixtures follow the mesh counters, count draws and growing area (02db49808)
- fix(vk): the mesh count draws bind their stages without RX_VK_LMEM_LOG's hook, which this base lacks (b41a03a9a)

Rebased onto main 7bacf846 as a plain commit on #705's (the topic merged #705 and #707 before; both are folded into this
PR): gpu/vk/VULKAN.md takes the topic merge 3d3939ad's resolution of #705 with #707, replayed by git merge-file (clean).
log_frame_stats keeps its closing brace, which that merge lost (d99221c42 put it back).

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #706 (#706), branch mac/indirect-quads at 6e6bc8d921 (Sweep3, on main aa95d35f).

It was stacked on #705; their changes are the earlier commits here.

Its own commits, squashed:
- fix(macos): quads provoke the same corners where the first vertex provokes (6e6bc8d92)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #708 (#708), branch mac/mesh-provoking at d24ecc70ec (Sweep3, on main aa95d35f).

It was stacked on #703, #707; their changes are the earlier commits here.

Merged with the topic's earlier commits by hand where they met (Consolidate-files/hand-resolutions.md).

Its own commits, squashed:
- fix(vk): the mesh fallback's rotation kept to what its list covers; the indirect quads counted for the provoking vertex; five checks follow (3a7b258ec)
- test: test_seg_xfer's fixture stands in fallback_draw_area (87f575c40)
- fix(macos): the mesh fallback's rotation follows the count draws and the growing records area (70686bc10)
- fix(macos): the mesh fallback's rotation decided and counted on macOS only, as ProvokingFirst's other gates (4800449a5)
- fix(macos): a rotated mesh fallback draw's area is cut only when its rotation list covers fewer corners than it holds (d24ecc70e)

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Hand resolution on restack/fix/indirect-quads, where #705 (IndirectQuads) meets topic/draw-path (#678, #680, #701, #703), as
Integration 36's 74da414a and Integration 37's eb4d02046 resolved it (only their hunks at this level: no PerfInstr hook, no mesh
fallback part).

- gpu/vk/vk_draw.cpp: #705's indirect quad draw is a sixth draw site in draw(). Its count gains ProvokingFirst's provoking_note
  (#703) and FanKey's census_fan_draw (#701), as the other sites and the direct quads' have them. Both return at once off Apple and
  off MoltenVK (provoking_first() is false off __APPLE__; census_fan_draw checks VK_DRIVER_ID_MOLTENVK): log-only counts, nothing
  recorded or drawn changes on any driver. Off Apple the two calls are the token change.
- tests/test_quad_draws.py (#705's): the direct quad draw as topic/draw-path has it, DrawIdDirect's record (rq) drawn from its
  words, then the count with provoking_note, then quad_drawn.
- tests/test_provoking_first.py (#703's): six census_draw sites, each with provoking_note (was five).
- tests/test_fan_key.py (#701's): three non-mesh sites of six counts (was two of five).
- tests/test_index8_bind.py (#678's): draw()'s indirect and direct branches found at a line's start (#705's rewrite gate holds a
  deeper "if (d.indirect) {" line first).
Each check keeps what it requires; none is dropped.

test_quad_draws, test_provoking_first and test_index8_bind failed at the merge before this commit; with it they pass, with
test_fan_key and test_fan_indirect, on arm64 and x86_64.

Rebased onto main 7bacf846 as a plain commit (it sat on #705's restack branch after a merge of topic/draw-path):
tests/test_provoking_first.py takes the topic merge 174d02096's text, replayed by git merge-file (clean); the whole tree
equals that merge replayed over its first parent.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Hand resolution on restack/fix/mesh-count, where #707 (MeshCountDraws) meets #680 (DrawIdDirect), a pair this restack first
combines. #707 declares BuiltIn DrawIndex for a stage loading DrawID except a mesh fallback's task or mesh stage (a GLCompute stage,
its draw index pushed); test_drawid_direct (#680's) pinned the old condition and failed ("spirv_emit_context.cpp declares
DrawIndex other than for a stage loading DrawID and the mesh-first task stage") at this restack and at topic draw-path-quads-mesh,
on arm64 and x86_64. It now pins the new one (DrawIdDirect's direct draws never come from those stages), and
program_reads_draw_index's comment says so: Integration 36's b4732392, its test_drawid_direct hunk and that comment only (its
perf_lines parts belong to topic mac-perf). No code change: the comment is the only vk_draw.cpp change.

test_drawid_direct: failing before this commit, passing with it, on arm64 and x86_64.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #704 (#704), branch mac/perf-instr at 040b840d97 (Sweep3, on main aa95d35f).

It was stacked on #679; their changes are the earlier commits here.

Merged with the topic's earlier commits by hand where they met (Consolidate-files/hand-resolutions.md).

Its own commits, squashed:
- feat(vk): log-only frame cost lines, a GPU timeline and the bench's A/B exactness arm, all off by default (43d7e8e89)
- test(vk): test_inline_write_order (main's, #329) includes perf_lines.h for full_barrier's bench arm (040b840d9)

Rebased onto main 7bacf846 (conflicts with #769 and #443, by hand): vk_replay.cpp includes main's hold_gpu.h and this
commit's vk_perf.h; replay() notes the op for PerfInstr (draw_perf_op) before main's part end right before a plain draw
(#443's split_part); maybe_split became part_ends_before_draw and split_part in main, and this commit's
perf_lines::why(PassEnd::PartSplit) sits in split_part after its refusals, where the part really ends.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #780 (#780), branch mac/load-clear at 12fe15f62d (Sweep3, on main aa95d35f).

It was stacked on #704; their changes are the earlier commits here.

Merged with the topic's earlier commits by hand where they met (Consolidate-files/hand-resolutions.md).

Its own commits, squashed:
- perf(macos): a pass's leading whole clears as its attachments' LOAD_OP_CLEAR on MoltenVK (MacPerf #7) (66b6b0234)
- fix(macos): load_clear's kept operations as a set of bits, its device line from the vendor fixes (1b86d46b2)
- fix(vk): LoadClear off by default (mirrors macos/integrated 2b4b7b8e, I40) (12fe15f62)

Rebased onto main 7bacf846 (conflict with #443, by hand): in replay() the held pass is settled before main's part end right
before a plain draw (split_part), so a part never ends with a held pass.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #782 (#782), branch mac/widen8 at 8b3eb471fb (Sweep3, on main aa95d35f).

It was stacked on #678, #703, #780; their changes are the earlier commits here.

Merged with the topic's earlier commits by hand where they met (Consolidate-files/hand-resolutions.md).

Its own commits, squashed:
- test: test_perf_lines reads draw()'s counted draws with ProvokingFirst's count line and FanKey's census (610309546)
- perf(macos): LS widens a pass's 8-bit indices itself on MoltenVK (8115c3272)
- fix(macos): restart-off 8-bit draws fetch 0xFF as vertex 255 on MoltenVK, as NVN does (84cd6d0c3)
- test: test_resolver_coverage lists widen8_before_draw's index binding (bf07ead64)
- fix(vk): one pass_keeps for LoadClear and Widen8; the widening checked right before a held begin (fe92e5378)
- fix(vk): Widen8's look ahead off by default; INDEX8_RAW stays on (mirrors macos/integrated 2b4b7b8e, I40) (8b3eb471f)

Rebased onto main 7bacf846 (after topic/draw-path's 67fd90bc closed draw_index8_report, which this commit's base lacked):
widen8_report(when) stays the function's last line, before that brace.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Was: #783 (#783), branch mac/mesh-batch at 7a196c0a99 (Sweep3, on main aa95d35f).

It was stacked on #708, #782; their changes are the earlier commits here.

Merged with the topic's earlier commits by hand where they met (Consolidate-files/hand-resolutions.md).

Its own commits, squashed:
- fix(vk): mesh count draws' pass end said MeshFallback; two checks follow mesh-count's moves (3d33cd202)
- vk: batch the mesh fallback's draws of a pass on MoltenVK (MeshBatch) (e5450f384)
- vk: MeshBatch's per-thread batch as a TLS_OBJECT (210a1f9fb)
- test: LoadClear, Widen8 and MeshBatch checked together at a pass's begin and end (7a196c0a9)

Rebased onto main 7bacf846 (conflict with #231, by hand): draw_begin_recording empties c1_at with main's reset() (its
array kept) before this commit's mesh_batch_recording_begun(r), and tests/test_mesh_batch.py asks for that reset();
main's tests/test_flat_map.py requires it.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
StreamRoom (reports/2026-11-15-stream-room.md). Run #36 (I40) left out 11,756 direct draws that depend on the provoking vertex
("no room for its list in the stream of the recording it was drawn in", count 4, not indexed; vk_draw.cpp:11764), I39's
MeshBatch-on runs 122-174 each (:11747, the same line). The stream was never short: the most a recording held was 292 KB of
2 MB and none grew. ProvokingFirst decides the list with the recording's command buffer, then draw() redirects the open mesh
batch's draws into its segment (mesh_batch_cmd), and provoking_write asked for cmd == rec_cmd: every list draw recorded in a
batch's pass was left out, its pipeline already the list's. How many depends on the frame's order of draws (#36: one more
batched pass a frame than I39's runs, holding such a draw).

- records_into_recording: the recording's command buffer, or the open batch's segment while its primary is that command
  buffer (executed there, in the same submission, after the stream is flushed). provoking_list and drawid_indirect ask it;
  a DrawIdDirect record of a draw in a segment is now taken from the stream too, as in the primary, instead of drawn direct
  with MoltenVK's stale draw index.
- provoking_room: the list's room is taken right after the draw's admission (the last place its recording can change, a
  handoff giving a new stream) and before the descriptors' uploads, so provoking_write only writes into it and cannot fail.
  No room there (RX_VK_STREAM_GROW_OFF, or no buffer made): the draw is drawn as it was with its own topology's pipeline
  (waited for, as a segmented variant is), logged and counted as "drawn as they were"; never left out. The tally's lost
  counter and the report's "left out, no room ..." clause go: nothing can count there now.
- Cost: none on the fast path. The list's stream_alloc moved from the draw to after the admission (the same bytes; a draw
  skipped between the two leaves its list's room unused until the recording ends); records_into_recording is cmd == rec_cmd
  first, the batch's state read only for another command buffer.

MoltenVK only (devices without provokingVertexLast; DrawIdDirect on MoltenVK; MeshBatch on MoltenVK). Tests:
tests/test_stream_room.py (new: run #36's frame under 32 switch sets, a stream filled between decision and draw, a handoff
into a stream that cannot hold the list, no memory there, a draw-index draw in a segment; every case fails on 2b4b7b8e),
test_provoking_first, test_drawid_direct (a segments case), test_widen8, test_seg_gathers, test_draw_side_effects updated.

Ported onto topic/mac-perf (StreamRoom's macos/stream-room, I40 2b4b7b8e; its every-platform second commit bbfb465f, the
direct quad draw's needed room, is a PR of its own): tests/seg_gathers_test.cpp's ProvokingFirst stand-ins replaced in
place, before FanIndirect's as the topic has them; test_provoking_first.py's docstring keeps the topic's gate (every device
off macOS counts nothing) with this commit's words; everything else line for line as on 2b4b7b8e.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
(cherry picked from commit ae7daf5fb708e4185a5d316edee1cd25e73515d9)
StreamRoom (reports/2026-11-15-stream-room.md). ae7daf5f's fallback, a ProvokingFirst draw whose list found no room after the
admission drawn as it was, asks graphics_pipeline() again for the plain variant with the game's topology, inside draw(). The
check that graphics_pipeline() is reached from draw() alone counted two calls; it now counts the three, two of them the plain
variant's. MoltenVK paths only (the fallback runs on devices without provokingVertexLast).

Ported onto topic/mac-perf after ae7daf5f's port (dd801607); line for line as on bbfb465f.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
(cherry picked from commit d987ab79a8a196ebf0712101c9da19d4886b2418)
On macOS (arm64, and x86_64 under Rosetta) collect_in reads the write marks
64 to a test with inline-asm 16-byte loads (ld1 .16b, movdqu) from any page,
then takes each mark read set in turn with the same relaxed load and acquire
exchange as before. Since the byte loads (a3f3001d8) the walk cost 0.31 ns a
mark there, 4-6 times Linux's word walk: about 0.7 ms of each submit on the
presenting thread (ReplayCPU #2).

The loads are the asm's own, not C accesses, so they race nothing in the C
memory model, and each byte they read is single-copy atomic: the writers'
granule and the byte loads'. Like those relaxed loads they order nothing and
only choose pages: the pages found, their order, the marks cleared and what a
found page's exchange makes visible are the byte walk's. Other systems keep
their walk unchanged (the vector walk is compiled out there).

HOS_COLLECT_VECTOR=0 (read once, logged) is the byte walk on the same build.
test_collect_wide compiles both walks and requires the same pages, order and
marks left on random marks and ranges (near page 0, at the array's end,
overlapping, dense), per arch; test_darwin_guest_memory takes the new code.

Ported onto topic/mac-perf (page-scan 74619b9b was on I40 7092f286, where every
system read the marks with the byte loads). Here the byte loads are macOS's only
(#480: elsewhere main's word loads, marks_clear_256), so:
- host/rx_backend.c: the vector walk goes in macOS's branch of collect_in, the
  byte walk its HOS_COLLECT_VECTOR=0 fallback; its code and its switch's reading
  sit under "defined(__APPLE__) && HOS_MARKS_VECTOR", so Windows and Linux compile
  exactly the walk they did (unifdef -U__APPLE__: the file's tokens unchanged);
- tests/test_collect_wide.py: on macOS the commit's fixture, both walks (the vector
  walk's text cut from its comment to collect_in); elsewhere the topic's fixture as
  it was (one walk against the plain one, the wide step counted through its memcpy);
- docs/development.md: HOS_COLLECT_WIDE's row says macOS's byte walk takes it with
  HOS_COLLECT_VECTOR=0; HOS_COLLECT_VECTOR's row as the commit's, without "as on the
  other systems".

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
(cherry picked from commit 74619b9b3f5553aa7d1ad8bc6384c42e2584a9b7)
In this topic #704's PerfInstr hook (perf_drawn after every counted draw) meets #705's IndirectQuads, whose one
vkCmdDrawIndexedIndirect is a sixth counted site in draw() (restacked, with provoking_note and FanKey's census,
a27f8f47): it gets the hook after the census, in the order the direct quads' site has them (count, census,
perf hook, quad_drawn), as I41's 74da414a. Log-only, off by default (RX_VK_PERF_LINES and the GPU timeline): what is
recorded and drawn does not change. test_perf_lines checks six sites (was five), with FanKey's census line at the
three non-mesh ones and FanIndirect's after it at the common end, exactly one place (I41's eb4d0204 form).

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
The stream-room port (dd801607) brought StreamRoom's fixture from I40, where provoking_list's gate is
"if (dev.provoking_vertex) return {};". In this topic #703 gates it with provoking_first() (a device without
provokingVertexLast, on macOS; every device off macOS asks NVN's last vertex of the device), defined outside the
lines the fixture cuts, so stream_room_test.cpp did not build. The fixture now cuts provoking_first too when the
tree has it (@PROVOKING_FIRST@); a tree without it (--source on I40) builds as before.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
The page-scan port (cd7dd435) took host/rx_backend.c from marks_clear to host_collect in one piece, as on I40, where
every system read the marks with byte loads. In this topic main's word-load test (marks_clear_256) sits between, in
the #else of macOS's marks_clear (#480), so the piece began inside an #if and did not compile ("#else without #if").
The fixture now takes macOS's marks_clear, the vector walk (its comment to collect_in) and collect_in, each whole.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
In this topic #702's test_fan_indirect (topic 6) cuts draw()'s indirect block, where #782 (Widen8) asks
widen8_range for a restart-off 8-bit draw's 16-bit bind with the pipeline's last_dyn.restart; its fixture had
neither, so it did not build at the topic's tip (it passes at #702's and #782's Sweep3 heads). It gets I41's stubs
(47f4695b): W8Bind and a widen8_range that widens nowhere, as on every driver but MoltenVK, and a last_dyn with
restart off. The fixture is now I41 78ec1c47's, byte for byte.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
The owner's decision (2026-11-15): LoadClear, #780's commit 30f0ebec5 here and off
by default since I40, leaves this topic. The E-series measured it at 0.1 ms of GPU
time a frame (E4c against E2), under the 0.17 ms run-to-run noise
(reports/2026-11-15-mac-perf-before-after.md), and only what is measured faster is
adopted.

Removed: gpu/vk/load_clear.h; the pass whose vkCmdBeginRendering is held for its
leading whole clears (pass_settle, draw_pass_held, draw_pass_settle, the replay's
keeps_lead); Targets::whole_extent; the clears' load-op path; vendor fix
load_clear and RX_VK_LOAD_CLEAR; the bench arm load_clear; its start-up line; the
L2 line's count of what each leading whole clear became; the docs' rows;
tests/test_load_clear.py.

begin_pass, the two clears and end_pass are again as #783 (MeshBatch) had them
before it was stacked on LoadClear (macos/mesh-batch 29b93740), and
test_mesh_batch.py and test_widen8.py check that form again (their checks at
29b93740 and macos/widen8 a0e18543). PerfInstr's L2 still counts the leading
whole clears a CLEAR load op would make free (#704's).

Rebased onto main 7bacf846 (conflict with #443, by hand): the held pass's settle leaves replay(); main's part end right
before a plain draw stays.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
The owner's decision (2026-11-15): Widen8's look ahead, #782's widening of a
pass's 8-bit indices before the pass and off by default since I40, leaves this
topic. The E-series measured it at 0.1 ms of GPU time a frame (E4b against E2),
under the 0.17 ms run-to-run noise (reports/2026-11-15-mac-perf-before-after.md),
because RX_VK_INDEX8_RAW already widens the restart-off draws at the draw; only
what is measured faster is adopted. #782's RX_VK_INDEX8_RAW stays.

Removed: gpu/vk/widen8_scan.h (the scan of the op stream ahead of a pass); the
replay's cursor (replay_cursor, replay_at, replay_end); vendor fix widen8,
dev.widen8 and RX_VK_WIDEN8 with its start-up line; widen8_on and the bench arm
widen8; the ranges widened before a pass in both forms, with their tallies and
census word; the restart form (Push's restart and census fields, widen8::map,
mapped, raw_at, pair_bytes, Range's second offset, Table::has).

Kept, what restart-off 8-bit draws draw unchanged: widen8_before_draw widens a
restart-off draw's indices zero-extended at the draw, its pass ended for it;
widen8_before_pass records that one range between the pass-start barrier and
the pass; widen8_range binds it for that draw and for later draws of the pass
with the same binding until a draw may write memory. The shader widens
zero-extended only; widen8_comp_spv.h is made again from it (glslang 16.6.0,
the command in widen8.comp). The log line counts only the widening at the draw.

Tests: tests/widen8_test.cpp drops the scan, the two forms and the look ahead's
timeline arms and keeps every value, the shader's words and census, the draws,
the table and the timeline with index8_raw on and off; tests/test_widen8.py
checks the widening at the draw and that the look ahead stays gone;
tests/stream_room_test.cpp's matrix loses its look-ahead switch (16 sets);
test_draw_binds.py and test_readback_part.py say what their counted sites are
now. Docs: the RX_VK_WIDEN8 row and the bench arm go; RX_VK_INDEX8_RAW's row
says what the draws bind.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Rebased onto main 7bacf846, imports_give_back's head carries main's #223 accounting
(`evicted_import_bytes -= ...` before #846's `destroy_import(p)`), and the fixture that
cuts that head out of vk_memory.cpp did not declare it: test_darwin_renderer failed to
compile on both architectures. The fixture now takes the variable's real declaration
from vk_memory.cpp, as it takes the pools' (nothing else changes; the test passes on
arm64 and on x86_64 under Rosetta).

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Rebased onto main 7bacf846, this topic meets main's tests/test_linux_pressure.py (#223),
which cuts the program cache's functions out of vk_progcache.cpp; #644's note of each
stage's OpArrayLength (`spirv_lengths::array_length`) is in those functions now, and the
fixture did not include the header that declares it: the test failed to compile.
tests/linux_pressure_test.cpp includes gpu/vk/spirv_lengths.h beside linux_pressure.h,
as vk_progcache.cpp does; nothing in the test changes (it passes on arm64 and on x86_64
under Rosetta).

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Takes 80a10018 (the Darwin renderer fixture declares main's evicted_import_bytes), the fix Sweep4's checks found at the rebased topic 2.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Takes b56a6cee (main's Linux pressure fixture includes spirv_lengths.h), the fix Sweep4's checks found at the rebased topic 3.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Rebased onto main 7bacf846, a recording's c1 uploads are main's #231 FlatMap keyed by the
stage's address (`FlatMap<uintptr_t, ...> c1_at`, `find(key)`, `[key]`), and two fixtures
of this topic did not build: test_seg_gathers cuts RecordingRes from vk_draw.cpp without
flat_map.h, and seg_bind_test.cpp's own RecordingRes kept the old
`unordered_map<const void*, ...>`. Both builds take `-include gpu/vk/flat_map.h` where the
tree has it (as main's own cut fixtures do), and seg_bind_test.cpp declares c1_at as the
tree does (HAVE_FLAT_C1, read from vk_draw.cpp); a base tree from before #231 builds as
before. Both tests pass on arm64 and on x86_64 under Rosetta.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Takes the fixes Sweep4's checks found at the rebased topics 2-4: 80a10018 (the Darwin renderer fixture declares main's evicted_import_bytes), b56a6cee (main's Linux pressure fixture includes spirv_lengths.h) and 74d8a42b (the segment fixtures take main's FlatMap c1_at).

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Rebased onto main 7bacf846, main's #713 moved the predicted keys' file read, its
`head[0] == program_cache_stamp()` check included, out of predicted_keys() into
predicted_keys_read(), and #701's test_fan_key looked for the check in predicted_keys():
"predicted_keys: not stamped with program_cache_stamp". The test now checks the same text in
predicted_keys_read() where the tree has it (predicted_keys() otherwise); nothing else
changes. Passes on arm64 and on x86_64 under Rosetta.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Takes the fixes Sweep4's checks found at the rebased topics 2-4: 80a10018 (the Darwin renderer fixture declares main's evicted_import_bytes), b56a6cee (main's Linux pressure fixture includes spirv_lengths.h) and 74d8a42b (the segment fixtures take main's FlatMap c1_at).

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Takes the fixes Sweep4's checks found at the rebased topics 2-4 and 6: 80a10018, b56a6cee and 74d8a42b (through topic 4) and e0cc1407 (the fan key test checks the predicted keys' stamp in main's reader).

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Takes the fixes Sweep4's checks found at the rebased topics 2-4 and 6: 80a10018, b56a6cee, 74d8a42b and e0cc1407 (through topics 4, 6 and 7).

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Rebased onto main 7bacf846, two of this topic's tests met main's code:
- test_perf_lines looked for PassEnd::PartSplit right before the pass end in maybe_split();
  main's #443 ends a part in split_part() (maybe_split calls it, or a plain draw asks for
  it), where the rebase put the `perf_lines::why(PassEnd::PartSplit)` line. The check
  reads split_part() where the tree has it ("void maybe_split: its pass end is not said
  to be PartSplit right before it" before).
- test_stream_room cuts RecordingRes, whose c1_at is main's #231 FlatMap: its build takes
  `-include gpu/vk/flat_map.h` where the tree has it, as main's cut fixtures do (it did not
  build).
Both pass on arm64 and on x86_64 under Rosetta.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
The one PR carries every macOS topic: mac-perf (topics 1-4, 6-8) and its sibling
precompile-metal (topic 5, on topic 4). Five files conflicted, each with both sides adding
at one place; each takes the order macos/integrated 63fc3d2c (I42) has for the same pair,
precompile-metal's lines first:
- gpu/vk/vk_draw.cpp: includes mode_census.h, private_memory.h, then count_draws.h ...
  mesh_batch.h; private_memory_bound (MetalScratch) before the ModeCensus and FanKey
  blocks; the skip log and the tries alone (compiler_service) before perf_dispatched.
- gpu/vk/vk_main.cpp and gpu/vk/vk_replay.cpp: thread_stack.h, then vk_perf.h.
- gpu/vk/vk_progcache.cpp: thread_stack.h, then fan_key.h.
- gpu/vk/vk_vendor.h: compiler_service, then index8_size and index8_raw, in the fields,
  in vendor_fixes and in vendor_fixes_env.
Every other file merged without a conflict.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Rebased onto main 7bacf846, main's tests/test_linux_pressure.py (#223) cuts vk_shader.h's
Stage and Program into its fixture, and this topic's Program holds a SegSig (`Program::seg`,
#658) over runtime_info.h's Shader::SegEntry: the fixture failed to compile ("unknown type
name 'SegSig'"). Where vk_shader.h has SegSig, the fixture cuts it too and takes a global
stand-in for SegEntry through `-include`, the one tests/test_program_cache_one_variant.py
uses; on a tree without SegSig nothing changes. Passes on arm64 and on x86_64 under Rosetta.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Takes the fix the one head's checks found in topic 4 (main's Linux pressure fixture stands in for SegSig's SegEntry).

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Takes 30627309 (main's Linux pressure fixture stands in for SegSig's SegEntry), found by the one head's checks.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Main's tests/test_linux_pressure.py (#223) cuts the program cache's functions out of
vk_progcache.cpp, which on this topic note each module's private memory through
private_memory.h (#651's MetalScratch: `private_memory::scan`, `local_weight`); the fixture
did not include the header and failed to compile. tests/linux_pressure_test.cpp includes
gpu/vk/private_memory.h as vk_progcache.cpp does (no check changed). Passes on arm64 and on
x86_64 under Rosetta.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Takes the fix the one head's checks found in topic 5 (main's Linux pressure fixture includes private_memory.h).

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
fix(macos): the mesh count draws' fallback binds are named under RX_VK_LMEM_LOG too
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request_target) Has been skipped
CI / Conventional Commit title (pull_request) Failing after 3s
CI / Workflow lint (actionlint) (pull_request) Successful in 6s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 5s
Third-party parts / As their notes say (pull_request) Successful in 12s
PR description / Description follows the template (pull_request_target) Successful in 6s
6343f29e07
A semantic of joining the topics: #651 (MetalScratch, topic 5) names each pipeline's first
bind with private_memory_bound right after every vkCmdBindPipeline of a mesh fallback's
compute stage, and #707's mesh count draws (topic 7) brought a new such bind, in its
`bind` lambda, without it (the two never met before the one head). Its test
(test_private_memory, source check) failed: "vkCmdBindPipeline(cmd,
VK_PIPELINE_BIND_POINT_COMPUTE, p.fallback_compute[stage]); is not followed by
private_memory_bound(...)". The lambda names the bind as the other fallback binds do, as
macos/integrated 63fc3d2c (I42) has it. Log-only, behind RX_VK_LMEM_LOG (private_memory::on()
is a constant test when unset). test_private_memory passes on arm64 and on x86_64 under
Rosetta.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Collaborator

Possibly related, for context:

  • PR #907 WIP: fix(vk): a direct quad draw's BaseVertex is its first vertex, as for every other non-indexed draw — Overlapping direct quad-draw renderer changes
  • PR #906 WIP: perf(vk): the mesh fallback's records line by line, or each vertex once and drawn indexed (RX_VK_MESH_FB_LAYOUT, off by default) — Overlapping mesh compute-fallback changes
Possibly related, for context: - PR #907 WIP: fix(vk): a direct quad draw's BaseVertex is its first vertex, as for every other non-indexed draw — Overlapping direct quad-draw renderer changes - PR #906 WIP: perf(vk): the mesh fallback's records line by line, or each vertex once and drawn indexed (RX_VK_MESH_FB_LAYOUT, off by default) — Overlapping mesh compute-fallback changes
Merge main a8a30c22 into macOS build
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 7s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 12s
CI / Workflow lint (actionlint) (pull_request) Successful in 13s
PR description / Description follows the template (pull_request_target) Has been cancelled
Third-party parts / As their notes say (pull_request) Successful in 15s
594d52963c
Preserve the Apple platform gates while integrating main's renderer, build and shared-tooling changes.
Resolve descriptor-array atomics, segmented writes, import lifetimes and compute-pipeline publication seams.
Validation: targeted merge tests, arm64/x86_64 translation units, renderer symbol closure and synthetic SPIR-V modules; inherited main failures remain documented.

Assisted-by: GPT-6 Astra
Co-Authored-By: GPT-6 Astra <[email protected]>
First-time contributor

Test report from a second Mac: an M1 Max (24-core GPU), 32 GB, macOS 27.0.1, at this PR's head 594d5296. It builds and plays. The scenes I reached look right. Three problems showed up that the M4 Max runs in the description don't show: the compiler service runs out of memory, every start is slow, and gameplay runs at single-digit frame rates.

(Disclosure: the testing and this write-up were done by an AI agent, Claude, on Matthew's Mac, with his permission. Every number below comes from the runs' own logs.)

Setup

  • Apple clang 21.0.0 (clang-2100.3.34.2). The SDK is Xcode beta's MacOSX27.2, not the Command Line Tools' 27.0, so xcrun gives a different MoltenVK hash.
  • MoltenVK 5189f8de + moltenvk-argbuf-slots.patch, built with the script in docs/macos-moltenvk.md. Universal SHA-256 ac45f2b0…, arm64 slice f961a4e1…, not the documented b4a59f07…; I believe that's the SDK difference. The renderer's line reads MoltenVK 1.4.3.
  • FFmpeg (libavcodec 63.1) with dav1d, static; SDL2 2.32.10, and the CPM headers package from tools.lock.
  • make_game.py --check caught my own FFmpeg's NEON objects declaring macOS 27 (requires macOS 27.0.0, newer than target 14.4). After a rebuild with MACOSX_DEPLOYMENT_TARGET set, it passed, and the build finished in one go.

What works

  • The opening plays: title, storybook cutscene, Link waking.
  • The repo's kokiri-start save loads.
  • I walked out of Link's house and down the ladder to Saria.
  • The control bridge's debug teleport took child Link to 15 maps, all drawn correctly as far as I can judge: Hyrule Field, Kakariko, Market, Hyrule Castle, Lost Woods, Sacred Forest Meadow, Graveyard, Death Mountain Trail, Death Mountain Crater, Goron City, Zora's River, Zora's Domain, Zora's Fountain, Gerudo Valley and Haunted Wasteland.
  • The Wasteland was black, but that teleport arrives by the Gerudo Fortress entrance, which child Link has no business using. Link was frozen at the arrival point, so I'm not counting it as a Mac problem.
  • No device loss and no crash of the game in about 2 hours of play over five starts.

Child Link in Kokiri Forest and 14 other maps, M1 Max

1. Metal's compiler service runs out of memory: 8 mesh fallback programs not made, their draws left out

  • During play, 8 mesh fallback compute pipelines were not made (-3) with its draws are left out:
    • ea4dd64df9c8f2b7 and 93e3e999f2fb9fd8: 1,087,607 SPIR-V words each, about 57 s per attempt.
    • 29a8af226b5afad2, 2d7d43c7cb9c077b, 38a34ca000b39f70, 682b5e6954b55941, 7b9d6679d826f98a and 7c6ca92f187ecd19: 85-93k words.
    • 4f0c0b40ab3a32cd: 66k words.
  • MoltenVK reports Compilation failed due to an interrupted connection: XPC_ERROR_CONNECTION_INTERRUPTED. This error occurred after multiple retries.
  • macOS wrote 25 MTLCompilerService crash reports overnight. They're SIGABRT from llvm::report_bad_alloc_error (in StringMapImpl::RehashTable, SROAPass::promoteAllocas / PromoteMemToReg, MachineRegisterInfo::createIncompleteVirtualRegister), plus SIGBUS in MachineOperand::setReg. In other words, the compiler runs out of memory on these programs.
  • The game process sat at about 22 GB on this 32 GB Mac, with swap nearly full (8.8 of 9.2 GB).
  • The shader preparation in make_game.py hit the same XPC errors (14 compute pipelines), but its retries made them all.
  • The description's run has "8 of 8 made, 0 XPC errors" on 64 GB, and lists RX_VK_ALONE_TRIES as untested for lack of such a failure. On 32 GB that failure is real.

2. Every start takes 18-28 minutes before the first frame

  • The start precompile, from the title-screen lines vk: precompile: ... programs ... in N ms:
    • Start 1: 336 s, with the default Metal cache already partly warm from the build.
    • Start 2: 509 s.
    • Start 3: 1,524 s, with RX_VK_METAL_CACHE_DIR set to a new empty folder.
    • Start 4: 1,676 s, same folder, now warm.
    • Start 5: 1,099 s.
  • The build's own shader preparation took 2,068 s.
  • With RX_VK_METAL_CACHE_DIR, Metal's files stopped growing at functions.data = 1,118,912,512 bytes and libraries.data ≈ 1.16 GB. That's within a few hundred KB of what the default per-user cache holds. My guess, not checked against Apple's docs: Metal caps each cache file near 1 GiB, so this game's ~38,000 pipelines never all stay cached and each start compiles much of the set again.
  • Separately, on macOS the log line vk: driver shader cache at the start: 0 MB (no folder found) only looks at NVIDIA's and Mesa's folders. It may want the Metal folder there instead.

3. Frame rate in play: 5-10 fps

  • At default settings, maps in play ran at 6-11 fps, with 1,000-2,500 draws a frame.
  • One RX_VK_PERF_LINES=1 period in play read GPU time 124.6 ms a frame (the longest submission 1247.8 ms). The menus read 12-23 ms, at 28-33 fps.
  • The precompile behind the game had finished (done, 43896 of 43896 items) before most of these readings, so the giant compiles aren't what's using the GPU.
  • The M1 Max's 24-core GPU should be slower than the M4 Max's 40 cores, but 125 ms against 19.4 ms looks like more than the core count. With the game at about 22 GB and swap almost full, memory pressure may be a large part of it. I haven't separated the two yet.

Logs for any of these are available on request. I'll keep testing adult Link and the dungeon interiors and add to this.

Test report from a second Mac: an **M1 Max (24-core GPU), 32 GB, macOS 27.0.1**, at this PR's head `594d5296`. It builds and plays. The scenes I reached look right. Three problems showed up that the M4 Max runs in the description don't show: the compiler service runs out of memory, every start is slow, and gameplay runs at single-digit frame rates. (Disclosure: the testing and this write-up were done by an AI agent, Claude, on Matthew's Mac, with his permission. Every number below comes from the runs' own logs.) **Setup** - Apple clang 21.0.0 (clang-2100.3.34.2). The SDK is Xcode beta's MacOSX27.2, not the Command Line Tools' 27.0, so `xcrun` gives a different MoltenVK hash. - MoltenVK `5189f8de` + `moltenvk-argbuf-slots.patch`, built with the script in `docs/macos-moltenvk.md`. Universal SHA-256 `ac45f2b0…`, arm64 slice `f961a4e1…`, not the documented `b4a59f07…`; I believe that's the SDK difference. The renderer's line reads `MoltenVK 1.4.3`. - FFmpeg (libavcodec 63.1) with dav1d, static; SDL2 2.32.10, and the CPM headers package from tools.lock. - `make_game.py --check` caught my own FFmpeg's NEON objects declaring macOS 27 (`requires macOS 27.0.0, newer than target 14.4`). After a rebuild with `MACOSX_DEPLOYMENT_TARGET` set, it passed, and the build finished in one go. **What works** - The opening plays: title, storybook cutscene, Link waking. - The repo's `kokiri-start` save loads. - I walked out of Link's house and down the ladder to Saria. - The control bridge's debug teleport took child Link to 15 maps, all drawn correctly as far as I can judge: Hyrule Field, Kakariko, Market, Hyrule Castle, Lost Woods, Sacred Forest Meadow, Graveyard, Death Mountain Trail, Death Mountain Crater, Goron City, Zora's River, Zora's Domain, Zora's Fountain, Gerudo Valley and Haunted Wasteland. - The Wasteland was black, but that teleport arrives by the Gerudo Fortress entrance, which child Link has no business using. Link was frozen at the arrival point, so I'm not counting it as a Mac problem. - No device loss and no crash of the game in about 2 hours of play over five starts. ![Child Link in Kokiri Forest and 14 other maps, M1 Max](https://git.magicbean.dev/attachments/379695d3-8e47-45e7-8483-7f0ae5f79eb8) **1. Metal's compiler service runs out of memory: 8 mesh fallback programs not made, their draws left out** - During play, 8 mesh fallback compute pipelines were `not made (-3)` with `its draws are left out`: - `ea4dd64df9c8f2b7` and `93e3e999f2fb9fd8`: 1,087,607 SPIR-V words each, about 57 s per attempt. - `29a8af226b5afad2`, `2d7d43c7cb9c077b`, `38a34ca000b39f70`, `682b5e6954b55941`, `7b9d6679d826f98a` and `7c6ca92f187ecd19`: 85-93k words. - `4f0c0b40ab3a32cd`: 66k words. - MoltenVK reports `Compilation failed due to an interrupted connection: XPC_ERROR_CONNECTION_INTERRUPTED. This error occurred after multiple retries`. - macOS wrote 25 `MTLCompilerService` crash reports overnight. They're `SIGABRT` from `llvm::report_bad_alloc_error` (in `StringMapImpl::RehashTable`, `SROAPass::promoteAllocas` / `PromoteMemToReg`, `MachineRegisterInfo::createIncompleteVirtualRegister`), plus `SIGBUS` in `MachineOperand::setReg`. In other words, the compiler runs out of memory on these programs. - The game process sat at about 22 GB on this 32 GB Mac, with swap nearly full (8.8 of 9.2 GB). - The shader preparation in `make_game.py` hit the same XPC errors (14 compute pipelines), but its retries made them all. - The description's run has "8 of 8 made, 0 XPC errors" on 64 GB, and lists `RX_VK_ALONE_TRIES` as untested for lack of such a failure. On 32 GB that failure is real. **2. Every start takes 18-28 minutes before the first frame** - The start precompile, from the title-screen lines `vk: precompile: ... programs ... in N ms`: - Start 1: 336 s, with the default Metal cache already partly warm from the build. - Start 2: 509 s. - Start 3: 1,524 s, with `RX_VK_METAL_CACHE_DIR` set to a new empty folder. - Start 4: 1,676 s, same folder, now warm. - Start 5: 1,099 s. - The build's own shader preparation took 2,068 s. - With `RX_VK_METAL_CACHE_DIR`, Metal's files stopped growing at `functions.data` = 1,118,912,512 bytes and `libraries.data` ≈ 1.16 GB. That's within a few hundred KB of what the default per-user cache holds. My guess, not checked against Apple's docs: Metal caps each cache file near 1 GiB, so this game's ~38,000 pipelines never all stay cached and each start compiles much of the set again. - Separately, on macOS the log line `vk: driver shader cache at the start: 0 MB (no folder found)` only looks at NVIDIA's and Mesa's folders. It may want the Metal folder there instead. **3. Frame rate in play: 5-10 fps** - At default settings, maps in play ran at 6-11 fps, with 1,000-2,500 draws a frame. - One `RX_VK_PERF_LINES=1` period in play read `GPU time 124.6 ms a frame (the longest submission 1247.8 ms)`. The menus read 12-23 ms, at 28-33 fps. - The precompile behind the game had finished (`done, 43896 of 43896 items`) before most of these readings, so the giant compiles aren't what's using the GPU. - The M1 Max's 24-core GPU should be slower than the M4 Max's 40 cores, but 125 ms against 19.4 ms looks like more than the core count. With the game at about 22 GB and swap almost full, memory pressure may be a large part of it. I haven't separated the two yet. Logs for any of these are available on request. I'll keep testing adult Link and the dungeon interiors and add to this.
First-time contributor

Follow-up from the same M1 Max (32 GB), same head 594d5296: adult Link and the dungeons, plus one device loss.

Adult world and dungeons draw correctly. The bridge's age adult worked, and the teleport reached every adult destination except the Crater, which I skipped so Link wouldn't burn:

  • The overworld: Kokiri Forest, Hyrule Field, Kakariko, Market, Ganon's Castle outside, Lost Woods, Sacred Forest Meadow, Graveyard, Death Mountain Trail, Goron City, Zora's River, Domain and Fountain, Gerudo Valley, Gerudo Fortress, Haunted Wasteland and Desert Colossus.
  • All 12 interiors: Deku Tree, Dodongo's Cavern, Jabu-Jabu, Forest, Fire, Water, Shadow and Spirit Temples, Bottom of the Well, Ice Cavern, Gerudo Training Ground and Ganon's Castle inside.

The Sheik scene in the Meadow played through, including the Minuet's ocarina prompt.

Adult overworld, M1 Max
Adult dungeons and interiors, M1 Max

Device lost once, about 70 s into a start. MoltenVK reported:

VK_ERROR_OUT_OF_DEVICE_MEMORY: Lost VkDevice after MTLCommandBuffer "vkQueueSubmit MTLCommandBuffer on Queue 0-0" execution failed (code 9): Invalid Resource (00000009:kIOGPUCommandBufferCallbackErrorInvalidResource)

Two things were unusual about that start:

  • It ran without the program cache. I had relaunched right after a longshot_ctl quit, and it logged program cache ...: another Longshot is using it: this one runs without it, so its precompile was 0 programs ... in 500 ms and everything compiled at first draw.
  • Swap was at 11.3 of 12.3 GB.

The next start, with the cache, played for about an hour with no device loss. I can't say which of the two matters, or whether either does.

More numbers for the earlier three points

  • Start to first frame on later starts: 522 s and 1,103 s. So far it ranges from 8.7 to 28 minutes, with the same RX_VK_METAL_CACHE_DIR folder.
  • In the latest session, 20 more XPC errors and 26 more MTLCompilerService crash reports. The same 8 mesh fallback programs were not made, plus the M4 Max run's 895-s giant 44511d69b52282ad.
  • vk: GPU time over 524 periods: median 90.5 ms a frame, max 228.5 ms (menus about 1-23 ms).

Frame time scales with render resolution, so it's GPU work, not paging. In adult Kokiri Forest, standing still (about 800-880 draws), I alternated the Insert menu's render resolution twice:

Render resolution vk: GPU time per frame fps
50% (1228x720) 88.2, 89.1, 88.3 ms; 111.4, 88.7, 88.9 ms 10.7
100% (2456x1440) 210.9, 210.6, 210.2 ms; 211.4, 210.4, 209.2 ms 3.9

Four times the pixels cost 2.4 times the GPU time. Even at 50% the GPU needs about 88 ms a frame, against 19.4 ms on the M4 Max in the description (I don't know the resolution of that run). A 24-core M1 Max should be slower than a 40-core M4 Max, but probably not 4-10x slower, so something in the frame may be much more expensive on this GPU family than on the M4. I tried to find which work it is:

  • RX_VK_PASS_TIMING=2 logs 0.00 ms for every span on MoltenVK, so its in-pass timestamps don't seem to work there.
  • A 4 s Metal System Trace (xctrace, Metal System Trace template, same spot, 50%, about 40 frames) attributes about 1.83 s of GPU time to fragment work, 1.17 s to compute and 0.16 s to vertex: roughly 46, 29 and 4 ms a frame. These are lower bounds: rows the export lists by reference were skipped.
  • The trace shows the GPU at its maximum performance state for 4.47 of the 4.48 s, so it isn't being clocked down.
  • The template collected no per-shader samples or counters. If you have a capture you'd like me to take, or a switch to run, I can do that on this Mac.

A caveat I should have put in the first comment: this Mac had other apps open (a browser among them), and swap was already about 11 GB before the game started. The memory numbers come from an ordinary desktop, not a clean machine. That's realistic for a player, but it makes the frame times and the compiler's out-of-memory failures worse than a fresh boot would.

Follow-up from the same M1 Max (32 GB), same head `594d5296`: adult Link and the dungeons, plus one device loss. **Adult world and dungeons draw correctly.** The bridge's `age adult` worked, and the teleport reached every adult destination except the Crater, which I skipped so Link wouldn't burn: - The overworld: Kokiri Forest, Hyrule Field, Kakariko, Market, Ganon's Castle outside, Lost Woods, Sacred Forest Meadow, Graveyard, Death Mountain Trail, Goron City, Zora's River, Domain and Fountain, Gerudo Valley, Gerudo Fortress, Haunted Wasteland and Desert Colossus. - All 12 interiors: Deku Tree, Dodongo's Cavern, Jabu-Jabu, Forest, Fire, Water, Shadow and Spirit Temples, Bottom of the Well, Ice Cavern, Gerudo Training Ground and Ganon's Castle inside. The Sheik scene in the Meadow played through, including the Minuet's ocarina prompt. ![Adult overworld, M1 Max](https://git.magicbean.dev/attachments/77c333e4-0d96-4f0b-83be-7e506e4fee79) ![Adult dungeons and interiors, M1 Max](https://git.magicbean.dev/attachments/e17f6234-426a-4d81-b385-0257860a76ab) **Device lost once, about 70 s into a start.** MoltenVK reported: > `VK_ERROR_OUT_OF_DEVICE_MEMORY: Lost VkDevice after MTLCommandBuffer "vkQueueSubmit MTLCommandBuffer on Queue 0-0" execution failed (code 9): Invalid Resource (00000009:kIOGPUCommandBufferCallbackErrorInvalidResource)` Two things were unusual about that start: - It ran without the program cache. I had relaunched right after a `longshot_ctl quit`, and it logged `program cache ...: another Longshot is using it: this one runs without it`, so its precompile was `0 programs ... in 500 ms` and everything compiled at first draw. - Swap was at 11.3 of 12.3 GB. The next start, with the cache, played for about an hour with no device loss. I can't say which of the two matters, or whether either does. **More numbers for the earlier three points** - Start to first frame on later starts: 522 s and 1,103 s. So far it ranges from 8.7 to 28 minutes, with the same `RX_VK_METAL_CACHE_DIR` folder. - In the latest session, 20 more XPC errors and 26 more `MTLCompilerService` crash reports. The same 8 mesh fallback programs were not made, plus the M4 Max run's 895-s giant `44511d69b52282ad`. - `vk: GPU time` over 524 periods: median 90.5 ms a frame, max 228.5 ms (menus about 1-23 ms). **Frame time scales with render resolution, so it's GPU work, not paging.** In adult Kokiri Forest, standing still (about 800-880 draws), I alternated the Insert menu's render resolution twice: | Render resolution | `vk: GPU time` per frame | fps | |---|---|---| | 50% (1228x720) | 88.2, 89.1, 88.3 ms; 111.4, 88.7, 88.9 ms | 10.7 | | 100% (2456x1440) | 210.9, 210.6, 210.2 ms; 211.4, 210.4, 209.2 ms | 3.9 | Four times the pixels cost 2.4 times the GPU time. Even at 50% the GPU needs about 88 ms a frame, against 19.4 ms on the M4 Max in the description (I don't know the resolution of that run). A 24-core M1 Max should be slower than a 40-core M4 Max, but probably not 4-10x slower, so something in the frame may be much more expensive on this GPU family than on the M4. I tried to find which work it is: - `RX_VK_PASS_TIMING=2` logs `0.00 ms` for every span on MoltenVK, so its in-pass timestamps don't seem to work there. - A 4 s Metal System Trace (`xctrace`, Metal System Trace template, same spot, 50%, about 40 frames) attributes about 1.83 s of GPU time to fragment work, 1.17 s to compute and 0.16 s to vertex: roughly 46, 29 and 4 ms a frame. These are lower bounds: rows the export lists by reference were skipped. - The trace shows the GPU at its maximum performance state for 4.47 of the 4.48 s, so it isn't being clocked down. - The template collected no per-shader samples or counters. If you have a capture you'd like me to take, or a switch to run, I can do that on this Mac. A caveat I should have put in the first comment: this Mac had other apps open (a browser among them), and swap was already about 11 GB before the game started. The memory numbers come from an ordinary desktop, not a clean machine. That's realistic for a player, but it makes the frame times and the compiler's out-of-memory failures worse than a fresh boot would.
First-time contributor

Test result on Apple silicon (macOS 14.5, Mac Studio, M2 Ultra, 128 GB):

  • Built 594d529 (arm64, minimum macOS 14.4) with LLVM 23.1.5 and MoltenVK 1.4.2.
  • The title screen, the Load menu, Kokiri Forest and Hyrule Field all render correctly; HUD, hearts, lighting and music are right.
  • Route: Continue from the repository save kokiri-start -> Kokiri Forest -> debug teleport HyruleField_Child; state play with the expected map and music, no crash once in play, about 30 s in each scene.
  • Frame rate: 11-12 fps at 1920x1080 in both scenes (the game's own presents lines: 11.4-11.9 fps). The run kept all networks (RX_VK_NETWORK_KEEP=all).
  • The intro movie also ran before that, at about 3 fps while its networks compiled.

This is an M2 Ultra at 1080p; the PR's M1 Max report was single digits, so the Apple silicon performance picture is consistent. The build needed a couple of local compatibility changes for this older macOS, outside the PR; the gameplay result above is unaffected.

Generated by opencode with deepseek-v4.1-flash-1017

Test result on Apple silicon (macOS 14.5, Mac Studio, M2 Ultra, 128 GB): - Built `594d529` (arm64, minimum macOS 14.4) with LLVM 23.1.5 and MoltenVK 1.4.2. - The title screen, the Load menu, Kokiri Forest and Hyrule Field all render correctly; HUD, hearts, lighting and music are right. - Route: Continue from the repository save `kokiri-start` -> Kokiri Forest -> debug teleport `HyruleField_Child`; `state play` with the expected map and music, no crash once in play, about 30 s in each scene. - Frame rate: 11-12 fps at 1920x1080 in both scenes (the game's own `presents` lines: 11.4-11.9 fps). The run kept all networks (`RX_VK_NETWORK_KEEP=all`). - The intro movie also ran before that, at about 3 fps while its networks compiled. This is an M2 Ultra at 1080p; the PR's M1 Max report was single digits, so the Apple silicon performance picture is consistent. The build needed a couple of local compatibility changes for this older macOS, outside the PR; the gameplay result above is unaffected. Generated by opencode with deepseek-v4.1-flash-1017
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 7s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 12s
CI / Workflow lint (actionlint) (pull_request) Successful in 13s
PR description / Description follows the template (pull_request_target) Has been cancelled
Third-party parts / As their notes say (pull_request) Successful in 15s
This pull request has changes conflicting with the target branch.
  • .gitignore
  • docs/development.md
  • gpu/vk/eden/shader_recompiler/backend/spirv/emit_spirv_mesh.cpp
  • gpu/vk/vk_api.h
  • gpu/vk/vk_draw.cpp
  • gpu/vk/vk_main.cpp
  • gpu/vk/vk_memory.cpp
  • gpu/vk/vk_replay.cpp
  • gpu/vk/vk_shader.cpp
  • gpu/vk/vk_texture.cpp
  • host/hos_sdl.h
  • host/posix/win32_posix.c
  • host/rx_backend.c
  • nx2/build.py
  • nx2/test_import_windows.py
  • tests/control_test.c
  • tests/display_startup_failure_test.cpp
  • tests/draw_stream_visibility_test.cpp
  • tests/fsr_uniform_ownership_test.cpp
  • tests/import_reach_test.cpp
  • tests/parallel_rb_refresh_test.cpp
  • tests/recording_admission_test.cpp
  • tests/test_control.py
  • tests/test_import_reach.py
  • tests/test_mirror_gpu_only.py
  • tests/test_parallel_rb_refresh.py
View command line instructions

Manual merge helper

Use this merge commit message when completing the merge manually.

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u 'mac/add-macos-build:mooki-mac/add-macos-build'
git switch 'mooki-mac/add-macos-build'
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
4 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
MagicBeanDev/Longshot!966
No description provided.