From dad2695fdea49c2318ce27ff6307892b77f6f533 Mon Sep 17 00:00:00 2001 From: Daniel Han Date: Sun, 31 May 2026 06:18:30 -0700 Subject: [PATCH] Studio: pin the last pre-macOS-26 llama.cpp prebuilt instead of walking back (#5896) * Studio: pin the last pre-macOS-26 llama.cpp prebuilt instead of walking back ggml-org moved their macOS build runner to macOS 26 (Tahoe) at b9428, so b9428 and every newer upstream prebuilt is stamped minos 26 and fails to dyld-load on macOS 14 / 15. #5883 handled this by walking back release by release at install time. Replace that with a deterministic pin: a host below macOS 26 selects b9415 directly (the last upstream build stamped below 26: arm64 minos 14, x64 minos 13.3), so it loads on macOS 13.3 / 14 / 15 / 26. Hosts on macOS 26+ and unknown-version hosts keep latest selection unchanged. Only the ggml-org upstream path is pinned; the unslothai/llama.cpp fork ships its own minos-13.3 prebuilts (#5893), so the pin is a no-op there and goes dormant once macOS routes to the fork. The Mach-O minos preflight from #5883 stays as a post-download backstop. Refs #5883, #5893. * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * docs: fork ships arm64 minos 14 / x64 minos 13.3, not uniform 13.3 The per-slice fork producer pins arm64 to 14.0 and x64 to 13.3; update the pinned_macos_release_tag docstring to match. No behavior change. --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: danielhanchen --- studio/install_llama_prebuilt.py | 46 +++++-- .../install/test_macos_version_compat.py | 46 ++++--- tests/studio/install/test_selection_logic.py | 127 ++++++++++++++++++ 3 files changed, 192 insertions(+), 27 deletions(-) diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py index 861a501570..2afd54bec9 100644 --- a/studio/install_llama_prebuilt.py +++ b/studio/install_llama_prebuilt.py @@ -169,6 +169,11 @@ DEFAULT_MAX_MACOS_RELEASE_FALLBACKS = env_int( 16, minimum = 1, ) +# Deterministic macOS pin. At b9428 ggml-org's macOS runner moved to macOS 26 +# (Tahoe), so b9428+ prebuilts only load on macOS 26+. b9415 is the last build +# stamped below 26 (arm64 minos 14, x64 minos 13.3); loads on macOS 13.3/14/15/26. +_PINNED_MACOS_FALLBACK_TAG = "b9415" +_PINNED_MACOS_LATEST_FLOOR = (26, 0) FORCE_COMPILE_DEFAULT_REF = os.environ.get("UNSLOTH_LLAMA_FORCE_COMPILE_REF", "master") DIRECT_LINUX_BUNDLE_PROFILES: dict[str, dict[str, Any]] = { @@ -1616,6 +1621,24 @@ def direct_upstream_release_plan( ) +def pinned_macos_release_tag(host: HostInfo, repo: str) -> str | None: + """Pin b9415 (the last upstream macOS build that loads below macOS 26) for a + known pre-26 host on ggml-org upstream; return None to keep latest selection. + The unslothai/llama.cpp fork ships its own prebuilts (arm64 minos 14, x64 + minos 13.3) and needs no pin, so this is a no-op there and for macOS 26+, + unknown version, non-macOS.""" + if repo != UPSTREAM_REPO: + return None + if not host.is_macos: + return None + version = host.macos_version + if version is None: + return None + if version >= _PINNED_MACOS_LATEST_FLOOR: + return None + return _PINNED_MACOS_FALLBACK_TAG + + def resolve_simple_install_release_plans( llama_tag: str, host: HostInfo, @@ -1629,15 +1652,15 @@ def resolve_simple_install_release_plans( allow_older_release_fallback = ( requested_tag == "latest" and not published_release_tag ) + # macOS: pin the last upstream build that loads on a pre-26 host instead of + # fetching the latest (macOS 26 only) build and walking back release by + # release. No-op on macOS 26+, unknown version, non-macOS, and the fork. + if allow_older_release_fallback: + pinned_macos = pinned_macos_release_tag(host, repo) + if pinned_macos is not None: + requested_tag = pinned_macos + allow_older_release_fallback = False release_limit = max(1, max_release_fallbacks) - # macOS may need to walk past a run of too-new prebuilts. Only when the host - # version is known; otherwise keep the default (cannot tell up front). - if ( - host.is_macos - and allow_older_release_fallback - and host.macos_version is not None - ): - release_limit = max(release_limit, DEFAULT_MAX_MACOS_RELEASE_FALLBACKS) plans: list[InstallReleasePlan] = [] last_error: PrebuiltFallback | None = None @@ -5303,9 +5326,10 @@ def preflight_macos_installed_binaries( install_dir: Path, host: HostInfo, ) -> None: - """Reject a macos prebuilt whose minimum-OS is newer than the host so the - release walk-back advances to the newest compatible release. No-op when the - host macOS version is unknown (runtime validation remains the backstop).""" + """Reject a macos prebuilt whose minimum-OS is newer than the host. The + upstream selector pins a loadable release up front, so here this is the + post-download backstop; the published/fork path also uses it to advance the + walk-back. No-op when the host macOS version is unknown (runtime validates).""" if not host.is_macos or host.macos_version is None: return issues = macos_binary_minos_issues(binaries, install_dir, host) diff --git a/tests/studio/install/test_macos_version_compat.py b/tests/studio/install/test_macos_version_compat.py index 0adc91a622..1b87e5af65 100644 --- a/tests/studio/install/test_macos_version_compat.py +++ b/tests/studio/install/test_macos_version_compat.py @@ -238,32 +238,46 @@ def _fake_macos_releases(tags): ] -class TestMacosReleaseWalkback: - """A known-version macOS host must generate enough older-release plans to - walk back past a run of too-new prebuilts; unknown-version and non-macOS - hosts keep the conservative 2-release default.""" +class TestMacosReleasePin: + """A known pre-26 macOS host deterministically pins the last upstream release + whose prebuilt loads on it (b9415) instead of walking back release by release; + macOS 26+ and unknown-version hosts keep normal latest selection with the + conservative 2-release default.""" - TAGS = [f"b{n}" for n in range(9437, 9400, -1)] # 37 newest-first releases + TAGS = [f"b{n}" for n in range(9442, 9400, -1)] # newest-first, includes b9415 def _patch_releases(self, monkeypatch): - monkeypatch.setattr( - ILP, - "iter_release_payloads_by_time", - lambda repo, published_release_tag, requested_tag: _fake_macos_releases( - self.TAGS - ), - ) + def fake_iter(repo, published_release_tag, requested_tag): + # The real iterator yields only the requested tag when one is pinned. + if requested_tag and requested_tag != "latest": + return _fake_macos_releases([requested_tag]) + return _fake_macos_releases(self.TAGS) - def test_known_macos_host_walks_back_deeper(self, monkeypatch): + monkeypatch.setattr(ILP, "iter_release_payloads_by_time", fake_iter) + + def test_pre26_host_pins_b9415(self, monkeypatch): self._patch_releases(monkeypatch) - _tag, plans = ILP.resolve_simple_install_release_plans( + tag, plans = ILP.resolve_simple_install_release_plans( "latest", make_macos_host((14, 0)), "ggml-org/llama.cpp", "", ) - assert len(plans) == ILP.DEFAULT_MAX_MACOS_RELEASE_FALLBACKS - assert len(plans) > ILP.DEFAULT_MAX_PREBUILT_RELEASE_FALLBACKS + assert tag == ILP._PINNED_MACOS_FALLBACK_TAG == "b9415" + assert len(plans) == 1 + assert plans[0].release_tag == "b9415" + + def test_tahoe_host_takes_latest(self, monkeypatch): + self._patch_releases(monkeypatch) + tag, plans = ILP.resolve_simple_install_release_plans( + "latest", + make_macos_host((26, 0)), + "ggml-org/llama.cpp", + "", + ) + assert tag == "latest" + assert plans[0].release_tag == self.TAGS[0] # newest release + assert len(plans) == ILP.DEFAULT_MAX_PREBUILT_RELEASE_FALLBACKS def test_unknown_macos_host_uses_default(self, monkeypatch): self._patch_releases(monkeypatch) diff --git a/tests/studio/install/test_selection_logic.py b/tests/studio/install/test_selection_logic.py index 16f47fa410..78aa9c480e 100644 --- a/tests/studio/install/test_selection_logic.py +++ b/tests/studio/install/test_selection_logic.py @@ -85,6 +85,10 @@ _windows_cuda_attempt_covers_blackwell = ( INSTALL_LLAMA_PREBUILT._windows_cuda_attempt_covers_blackwell ) resolve_release_asset_choice = INSTALL_LLAMA_PREBUILT.resolve_release_asset_choice +pinned_macos_release_tag = INSTALL_LLAMA_PREBUILT.pinned_macos_release_tag +resolve_simple_install_release_plans = ( + INSTALL_LLAMA_PREBUILT.resolve_simple_install_release_plans +) # --------------------------------------------------------------------------- @@ -2631,3 +2635,126 @@ class TestResolveUpstreamAssetChoice: result = resolve_upstream_asset_choice(host, self.TAG) assert result.install_kind == "windows-cuda" assert result.name == cuda_name + + +# =========================================================================== +# N.2. Deterministic macOS prebuilt pin (b9415) +# =========================================================================== + + +def _macos_host(machine = "arm64", version = (15, 5)): + return make_host( + system = "Darwin", + machine = machine, + nvidia_smi = None, + driver_cuda_version = None, + compute_caps = [], + has_physical_nvidia = False, + has_usable_nvidia = False, + macos_version = version, + ) + + +class TestPinnedMacosReleaseTag: + """pinned_macos_release_tag: pin b9415 only for ggml-org upstream macOS hosts + below macOS 26; latest (None) for 26+, unknown version, the fork, non-macOS.""" + + def test_arm64_sequoia_pins_b9415(self): + host = _macos_host("arm64", (15, 5)) + assert pinned_macos_release_tag(host, UPSTREAM_REPO) == "b9415" + + def test_arm64_sonoma_pins_b9415(self): + host = _macos_host("arm64", (14, 7)) + assert pinned_macos_release_tag(host, UPSTREAM_REPO) == "b9415" + + def test_x64_ventura_13_3_pins_b9415(self): + # b9415's Intel slice is minos 13.3, so 13.3 Intel hosts still load it. + host = _macos_host("x86_64", (13, 3)) + assert pinned_macos_release_tag(host, UPSTREAM_REPO) == "b9415" + + def test_tahoe_26_0_takes_latest(self): + host = _macos_host("arm64", (26, 0)) + assert pinned_macos_release_tag(host, UPSTREAM_REPO) is None + + def test_tahoe_26_1_takes_latest(self): + host = _macos_host("arm64", (26, 1)) + assert pinned_macos_release_tag(host, UPSTREAM_REPO) is None + + def test_unknown_version_takes_latest(self): + host = _macos_host("arm64", None) + assert pinned_macos_release_tag(host, UPSTREAM_REPO) is None + + def test_fork_repo_is_dormant(self): + # The unslothai/llama.cpp fork publishes its own minos-13.3 prebuilts. + host = _macos_host("arm64", (15, 5)) + fork = INSTALL_LLAMA_PREBUILT.DEFAULT_PUBLISHED_REPO + assert pinned_macos_release_tag(host, fork) is None + + def test_non_macos_host_is_dormant(self): + host = make_host(system = "Linux", machine = "x86_64") + assert pinned_macos_release_tag(host, UPSTREAM_REPO) is None + + +class TestResolveSimpleMacosPin: + """End to end on the simple/upstream path macOS actually uses: a pre-26 host + deterministically resolves b9415 (no walk-back); a macOS 26 host takes the + latest release. Mirrors how setup.sh routes Darwin to ggml-org/llama.cpp.""" + + TAGS = ["b9442", "b9430", "b9428", "b9415"] # newest-first feed + + def _feed(self, monkeypatch): + calls = [] + + def _release(tag): + name = f"llama-{tag}-bin-macos-arm64.tar.gz" + return { + "tag_name": tag, + "assets": [ + { + "name": name, + "browser_download_url": f"https://example.com/{name}", + } + ], + } + + def fake_iter(repo, published_release_tag = "", requested_tag = ""): + calls.append((repo, published_release_tag, requested_tag)) + # Emulate the real iterator: a specific tag yields only that release. + if requested_tag and requested_tag != "latest": + yield _release(requested_tag) + return + for tag in self.TAGS: + yield _release(tag) + + monkeypatch.setattr( + INSTALL_LLAMA_PREBUILT, "iter_release_payloads_by_time", fake_iter + ) + return calls + + def test_pre26_host_pins_b9415_without_walkback(self, monkeypatch): + calls = self._feed(monkeypatch) + host = _macos_host("arm64", (15, 5)) + requested_tag, plans = resolve_simple_install_release_plans( + "latest", host, "ggml-org/llama.cpp", "" + ) + assert requested_tag == "b9415" + assert len(plans) == 1 + assert plans[0].release_tag == "b9415" + assert plans[0].llama_tag == "b9415" + assert plans[0].attempts[0].install_kind == "macos-arm64" + assert plans[0].attempts[0].name == "llama-b9415-bin-macos-arm64.tar.gz" + # The pin overrode the requested tag before any release was fetched. + assert calls[0][2] == "b9415" + # Simple/upstream path stays unverified-by-manifest, exactly as before. + assert plans[0].approved_checksums.artifacts == {} + + def test_tahoe_host_takes_latest_release(self, monkeypatch): + calls = self._feed(monkeypatch) + host = _macos_host("arm64", (26, 0)) + requested_tag, plans = resolve_simple_install_release_plans( + "latest", host, "ggml-org/llama.cpp", "" + ) + assert requested_tag == "latest" + assert plans[0].release_tag == "b9442" + # No pin: the iterator was asked for latest, not a specific tag. + assert calls[0][2] == "latest"