Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

95.9 KB
Raw Blame
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0

"""Skips are legal only with a recorded prior run, identical inputs and a passing on-disk check."""

from __future__ import annotations

import ast
import importlib.util
import json
import os
import pathlib
import platform
import re
import shutil
import sys
import tempfile
import types

import pytest

REPO_ROOT = pathlib.Path(__file__).resolve().parents[3]
STACK_PATH = REPO_ROOT / "studio" / "install_python_stack.py"


def _load():
    sys.path.insert(0, str(REPO_ROOT / "studio"))
    try:
        spec = importlib.util.spec_from_file_location("studio_stack_pass_skips", STACK_PATH)
        module = importlib.util.module_from_spec(spec)
        sys.modules[spec.name] = module
        spec.loader.exec_module(module)
    finally:
        if sys.path and sys.path[0] == str(REPO_ROOT / "studio"):
            sys.path.pop(0)
    return module


stack = _load()


@pytest.fixture
def manifest(monkeypatch, tmp_path):
    """A manifest and requirements tree that _plan_pass would accept."""
    req_root = tmp_path / "requirements"
    (req_root / "single-env").mkdir(parents = True)
    for name in stack.install_manifest.PASS_INPUT_FILES:
        (req_root / name).write_text(f"# {name}\n", encoding = "utf-8")
    monkeypatch.setattr(stack, "REQ_ROOT", req_root)
    monkeypatch.setattr(stack, "CONSTRAINTS", req_root / "single-env" / "constraints.txt")
    monkeypatch.setattr(stack, "NO_TORCH", False)
    monkeypatch.setattr(stack, "IS_MAC_ARM", False)
    monkeypatch.setattr(stack, "IS_WINDOWS", False)
    monkeypatch.setattr(stack, "PLATFORM_LACKS_TORCHCODEC_WHEEL", False)
    monkeypatch.setattr(stack, "_expected_torch_flavor_tag", lambda: "cpu")
    monkeypatch.setattr(stack, "_recordable_torch_flavor_tag", lambda tag: tag)
    payload = {
        "schema": stack.install_manifest.MANIFEST_SCHEMA,
        "python": platform.python_version(),
        "platform": f"{sys.platform}-{platform.machine()}",
        "no_torch": False,
        "expected_torch_tag": "cpu",
        "installer_python_tag": stack._installer_python_tag(),
        "pass_inputs": stack.install_manifest.pass_input_digests(req_root),
        "step_results": {name: "ran" for name in stack.install_manifest.PASS_INPUT_FILES},
    }
    monkeypatch.setattr(stack.install_manifest, "read_manifest", lambda *a, **k: dict(payload))
    monkeypatch.setattr(
        stack.install_manifest, "verify_install", lambda *a, **k: {"ok": True, "reason": None}
    )
    return payload, req_root


def _plan(**kwargs):
    return stack._plan_pass(
        kwargs.pop("package_name", "unsloth"), kwargs.pop("local_repo", ""), kwargs.pop("ci", "")
    )


def test_a_clean_manifest_plans_a_skippable_pass(manifest) -> None:
    plan = _plan()
    assert plan is not None
    assert plan["pass_inputs"] == manifest[0]["pass_inputs"]


@pytest.mark.parametrize("value", ["1", "true", "YES", "on"])
def test_full_deps_forces_everything(monkeypatch, manifest, value) -> None:
    """The escape hatch. A skip nobody can turn off is a bug nobody can work around."""
    monkeypatch.setenv(stack._FULL_DEPS_ENV, value)
    assert _plan() is None


@pytest.mark.parametrize("value", ["0", "false", "", "maybe"])
def test_a_non_true_full_deps_value_changes_nothing(monkeypatch, manifest, value) -> None:
    monkeypatch.setenv(stack._FULL_DEPS_ENV, value)
    assert _plan() is not None


def test_a_peer_already_in_a_pass_forces_everything(monkeypatch, manifest) -> None:
    """Its packages are the ones this evidence describes, so nothing may be skipped on it."""
    monkeypatch.setattr(stack, "_PASS_UNCONTENDED", False)
    assert _plan() is None


def test_the_pass_runs_inside_the_pass_lock() -> None:
    """The flag has to cover the whole pass: a lock dropped early proves nothing."""
    source = STACK_PATH.read_text(encoding = "utf-8")
    assert "@_under_pass_lock\ndef install_python_stack() -> int:" in source
    wrapper = source[source.index("def _under_pass_lock(") : source.index("@_under_pass_lock")]
    assert "with install_manifest.pass_lock() as uncontended:" in wrapper
    assert "return func(*args, **kwargs)" in wrapper


@pytest.mark.parametrize(
    "kwargs",
    [
        {"local_repo": "/checkout"},
        {"ci": "1"},
        {"package_name": "unsloth-nightly"},
    ],
)
def test_dev_shapes_never_skip(manifest, kwargs) -> None:
    """An editable overlay or another package name means the tree on disk is not the
    tree the manifest describes, and its digests describe neither."""
    assert _plan(**kwargs) is None


@pytest.mark.parametrize(
    "mutation",
    [
        {"schema": 2},
        {"pass_inputs": None},
        {"step_results": None},
        {"pass_inputs": "not a dict"},
        {"python": "3.0.0"},
        # A GIL and a free-threaded build share the version string; only the tag differs.
        {"installer_python_tag": "999t"},
        {"installer_python_tag": None},
        {"platform": "sunos-vax"},
        {"no_torch": True},
        {"no_torch": None},
        {"expected_torch_tag": "cu128"},
        {"expected_torch_tag": None},
    ],
)
def test_a_moved_input_forces_a_full_pass(monkeypatch, manifest, mutation) -> None:
    payload, _req_root = manifest
    payload.update(mutation)
    monkeypatch.setattr(stack.install_manifest, "read_manifest", lambda *a, **k: dict(payload))
    assert _plan() is None


def test_no_manifest_at_all_forces_a_full_pass(monkeypatch, manifest) -> None:
    monkeypatch.setattr(stack.install_manifest, "read_manifest", lambda *a, **k: None)
    monkeypatch.setattr(stack.install_manifest, "read_previous_manifest", lambda *a, **k: None)
    assert _plan() is None


def test_a_parked_manifest_is_evidence_when_the_live_one_is_gone(monkeypatch, manifest) -> None:
    """setup.ps1 parks the manifest before the installer starts; the pass still has to
    find last run's evidence there, and verify the tree against that same copy."""
    payload, _ = manifest
    seen = {}
    monkeypatch.setattr(stack.install_manifest, "read_manifest", lambda *a, **k: None)
    monkeypatch.setattr(
        stack.install_manifest, "read_previous_manifest", lambda *a, **k: dict(payload)
    )

    def _verify(*a, **k):
        seen["manifest"] = k.get("manifest")
        return {"ok": True, "reason": None}

    monkeypatch.setattr(stack.install_manifest, "verify_install", _verify)
    plan = _plan()
    assert plan is not None
    assert plan["pass_inputs"] == payload["pass_inputs"]
    assert seen["manifest"] == payload


def test_a_damaged_install_forces_a_full_pass(monkeypatch, manifest) -> None:
    """verify_install(deep=True) is the only check that walks the filesystem, and it is
    the one that catches a payload quarantined after the manifest was written."""
    monkeypatch.setattr(
        stack.install_manifest,
        "verify_install",
        lambda *a, **k: {"ok": False, "reason": "studio_install_damaged"},
    )
    assert _plan() is None


def test_a_probe_that_raises_forces_a_full_pass(monkeypatch, manifest) -> None:
    def boom(*_a, **_k):
        raise RuntimeError("the venv is unreadable")

    monkeypatch.setattr(stack.install_manifest, "verify_install", boom)
    assert _plan() is None
    monkeypatch.setattr(stack, "_expected_torch_flavor_tag", boom)
    assert _plan() is None


@pytest.fixture
def gated(monkeypatch, manifest):
    payload, req_root = manifest
    monkeypatch.setattr(stack, "_PASS_EVIDENCE", _plan())
    monkeypatch.setattr(stack, "_CONSTRAINTS_CACHE", None)
    monkeypatch.setattr(stack, "_INSTALL_ACTIONS", 0)
    monkeypatch.setattr(stack.install_manifest, "missing_requirements", lambda *a, **k: [])
    monkeypatch.setattr(stack.install_manifest, "violated_constraints", lambda *a, **k: [])
    return payload, req_root


def test_a_step_with_unchanged_inputs_is_skipped(gated) -> None:
    _payload, req_root = gated
    assert stack._requirements_satisfied(req_root / "studio.txt", no_deps = False) is True


def test_nothing_is_skipped_without_evidence(monkeypatch, gated) -> None:
    _payload, req_root = gated
    monkeypatch.setattr(stack, "_PASS_EVIDENCE", None)
    assert stack._requirements_satisfied(req_root / "studio.txt", no_deps = False) is False


def test_a_step_the_last_run_never_reached_is_not_skipped(monkeypatch, gated) -> None:
    """The manifest is written at the end, so a pass killed after step 8 records
    nothing for step 9. Absent must never read as done."""
    evidence = dict(stack._PASS_EVIDENCE)
    evidence["step_results"] = {
        key: value for key, value in evidence["step_results"].items() if key != "studio.txt"
    }
    monkeypatch.setattr(stack, "_PASS_EVIDENCE", evidence)
    assert stack._requirements_satisfied(gated[1] / "studio.txt", no_deps = False) is False


def test_a_one_byte_edit_to_the_file_runs_the_step(gated) -> None:
    _payload, req_root = gated
    (req_root / "studio.txt").write_text("# studio.txt \n", encoding = "utf-8")
    assert stack._requirements_satisfied(req_root / "studio.txt", no_deps = False) is False


def test_a_moved_constraint_runs_every_constrained_step(gated) -> None:
    """A constraint that moved under an unchanged requirements file is exactly what
    digest equality on the file alone cannot see."""
    _payload, req_root = gated
    (req_root / "single-env" / "constraints.txt").write_text("numpy<2\n", encoding = "utf-8")
    assert stack._requirements_satisfied(req_root / "studio.txt", no_deps = False) is False
    assert (
        stack._requirements_satisfied(
            req_root / "triton-kernels.txt", no_deps = True, constrain = False
        )
        is True
    )


def test_the_mac_overrides_file_counts_on_mac_arm(monkeypatch, gated) -> None:
    """It reaches uv through UV_OVERRIDE rather than the command line, so nothing else
    in the recorded inputs would notice it moving."""
    _payload, req_root = gated
    monkeypatch.setattr(stack, "IS_MAC_ARM", True)
    assert stack._requirements_satisfied(req_root / "studio.txt", no_deps = False) is True
    (req_root / "single-env" / "overrides-darwin-arm64.txt").write_text("x\n", encoding = "utf-8")
    assert stack._requirements_satisfied(req_root / "studio.txt", no_deps = False) is False


def test_an_uninstalled_requirement_runs_the_step(monkeypatch, gated) -> None:
    """(c): the output has to still be on disk. A venv edited after the install is the
    case a recorded digest cannot see."""
    _payload, req_root = gated
    monkeypatch.setattr(stack.install_manifest, "missing_requirements", lambda *a, **k: ["rich"])
    assert stack._requirements_satisfied(req_root / "studio.txt", no_deps = False) is False


def test_a_violated_constraint_runs_the_step(monkeypatch, gated) -> None:
    _payload, req_root = gated
    monkeypatch.setattr(stack.install_manifest, "violated_constraints", lambda *a, **k: ["numpy"])
    monkeypatch.setattr(stack, "_CONSTRAINTS_CACHE", None)
    assert stack._requirements_satisfied(req_root / "studio.txt", no_deps = False) is False


def test_a_file_outside_the_requirements_tree_is_never_skipped(gated) -> None:
    """--local points base.txt somewhere else; there is no manifest key for it."""
    _payload, req_root = gated
    assert stack._requirements_satisfied(req_root.parent / "elsewhere.txt", no_deps = False) is False


def test_the_constraint_scan_is_redone_after_an_install(monkeypatch, gated) -> None:
    """Cached per pass, because every gated step asks -- but a step that installed
    something can have satisfied or broken a constraint the next step reads."""
    answers = iter([["numpy"], []])
    monkeypatch.setattr(
        stack.install_manifest, "violated_constraints", lambda *a, **k: next(answers)
    )
    monkeypatch.setattr(stack, "_CONSTRAINTS_CACHE", None)
    assert stack._violated_constraints() == ["numpy"]
    assert stack._violated_constraints() == ["numpy"]
    stack._count_install_action()
    assert stack._violated_constraints() == []


def test_the_progress_slot_is_spent_either_way(monkeypatch, gated) -> None:
    """The denominator cannot depend on how much of the install was already there."""
    _payload, req_root = gated
    seen: list[str] = []
    monkeypatch.setattr(stack, "_progress", seen.append)
    assert stack._skip_step(req_root / "studio.txt", "studio deps", no_deps = False) is True
    monkeypatch.setattr(stack, "_PASS_EVIDENCE", None)
    assert stack._skip_step(req_root / "studio.txt", "studio deps", no_deps = False) is False
    assert seen == ["studio deps (satisfied, skipped)", "studio deps"]


def test_an_extra_check_can_veto_a_skip(monkeypatch, gated) -> None:
    _payload, req_root = gated
    monkeypatch.setattr(stack, "_progress", lambda *_a: None)
    assert (
        stack._skip_step(
            req_root / "studio.txt", "studio deps", no_deps = False, extra_check = lambda: False
        )
        is False
    )
    assert (
        stack._skip_step(
            req_root / "studio.txt", "studio deps", no_deps = False, extra_check = lambda: True
        )
        is True
    )


def test_the_gate_audits_the_file_the_install_would_use(monkeypatch, tmp_path) -> None:
    """extras.txt names torchcodec and three platforms filter it out. Auditing the raw
    file would report it missing on every one of them and never skip anything again."""
    req = tmp_path / "extras.txt"
    req.write_text("rich\ntorchcodec\n", encoding = "utf-8")
    monkeypatch.setattr(stack, "IS_WINDOWS", False)
    monkeypatch.setattr(stack, "NO_TORCH", False)
    monkeypatch.setattr(stack, "PLATFORM_LACKS_TORCHCODEC_WHEEL", True)
    effective, temps = stack._effective_requirements(req)
    try:
        assert effective != req
        assert effective.read_text(encoding = "utf-8") == "rich\n"
    finally:
        for temp in temps:
            temp.unlink(missing_ok = True)


def test_an_unfiltered_file_is_used_as_is(monkeypatch, tmp_path) -> None:
    req = tmp_path / "extras.txt"
    req.write_text("rich\n", encoding = "utf-8")
    monkeypatch.setattr(stack, "IS_WINDOWS", False)
    monkeypatch.setattr(stack, "NO_TORCH", False)
    monkeypatch.setattr(stack, "PLATFORM_LACKS_TORCHCODEC_WHEEL", False)
    effective, temps = stack._effective_requirements(req)
    assert effective == req and temps == []


def test_pip_install_and_the_gate_share_one_filter() -> None:
    """Two copies of the filter list is how the two would disagree, and a disagreement
    here reads as "already installed" for a package the install never had."""
    source = STACK_PATH.read_text(encoding = "utf-8")
    body = source[source.index("def pip_install(") : source.index("def download_file(")]
    assert "_effective_requirements(req)" in body
    assert "_filter_requirements(" not in body


def test_a_git_requirement_is_matched_by_ref_not_version(monkeypatch, tmp_path) -> None:
    """The same version is published from every branch, so a release/3.6.x pin is satisfied on paper
    by a main build; direct_url.json is the only place the ref survives install."""
    req = tmp_path / "triton-kernels.txt"
    req.write_text(
        "# comment\n"
        "triton_kernels @ git+https://example.invalid/triton.git@release/3.6.x"
        "#subdirectory=python/triton_kernels\n",
        encoding = "utf-8",
    )
    assert stack._direct_reference_in_requirements(req) == (
        "https://example.invalid/triton.git",
        "release/3.6.x",
        "python/triton_kernels",
    )

    commit = "0123456789abcdef0123456789abcdef01234567"
    req.write_text(
        f"triton_kernels @ git+https://example.invalid/triton.git@{commit}"
        "#subdirectory=python/triton_kernels\n",
        encoding = "utf-8",
    )
    recorded = {
        "url": "https://example.invalid/triton.git",
        "subdirectory": "python/triton_kernels",
        "vcs_info": {"vcs": "git", "requested_revision": commit},
    }

    class _Dist:
        def __init__(self, payload):
            self._payload = payload

        def read_text(self, _name):
            return json.dumps(self._payload) if self._payload is not None else None

    import importlib.metadata

    def _distribution(payload):
        return lambda _name: _Dist(payload)

    monkeypatch.setattr(importlib.metadata, "distribution", _distribution(recorded))
    assert stack._direct_reference_is_installed(req, "triton_kernels") is True
    # uv records the URL without ".git".
    uv_shape = {**recorded, "url": "https://example.invalid/triton"}
    monkeypatch.setattr(importlib.metadata, "distribution", _distribution(uv_shape))
    assert stack._direct_reference_is_installed(req, "triton_kernels") is True

    for broken in (
        {**recorded, "vcs_info": {"vcs": "git", "requested_revision": "main"}},
        {**recorded, "url": "https://example.invalid/other.git"},
        {**recorded, "subdirectory": "python/other"},
        {"url": recorded["url"]},
        None,
    ):
        monkeypatch.setattr(importlib.metadata, "distribution", _distribution(broken))
        assert stack._direct_reference_is_installed(req, "triton_kernels") is False


def test_a_mutable_git_ref_is_evidence_only_while_the_remote_still_points_at_it(
    tmp_path, monkeypatch, capsys
) -> None:
    """A moving git ref is evidence only while the remote still points at the recorded commit."""
    req = tmp_path / "t.txt"
    req.write_text(
        "triton_kernels @ git+https://example.invalid/triton.git@release/3.6.x"
        "#subdirectory=python/triton_kernels\n",
        encoding = "utf-8",
    )
    commit = "0123456789abcdef0123456789abcdef01234567"
    recorded = {
        "url": "https://example.invalid/triton.git",
        "subdirectory": "python/triton_kernels",
        "vcs_info": {"vcs": "git", "requested_revision": "release/3.6.x", "commit_id": commit},
    }

    class _Dist:
        def __init__(self, payload):
            self._payload = payload

        def read_text(self, _name):
            return json.dumps(self._payload)

    import importlib.metadata

    monkeypatch.setattr(importlib.metadata, "distribution", lambda _name: _Dist(recorded))
    asked: list = []

    def _remote(answer):
        def _ask(
            url,
            revision,
            timeout = 45,
        ):
            asked.append((url, revision))
            return answer

        return _ask

    monkeypatch.setattr(stack, "_git_remote_commit", _remote(commit))
    assert stack._direct_reference_is_installed(req, "triton_kernels") is True
    assert asked == [("https://example.invalid/triton.git", "release/3.6.x")]

    monkeypatch.setattr(stack, "_git_remote_commit", _remote("f" * 40))
    assert stack._direct_reference_is_installed(req, "triton_kernels") is False

    monkeypatch.setattr(stack, "_git_remote_commit", _remote(None))
    assert stack._direct_reference_is_installed(req, "triton_kernels") is True
    # Whitespace-normalised: _note wraps to the terminal width (80 columns under xdist).
    assert "keeping the installed build 0123456789ab" in " ".join(capsys.readouterr().out.split())

    without_commit = {**recorded, "vcs_info": {"vcs": "git", "requested_revision": "release/3.6.x"}}
    monkeypatch.setattr(importlib.metadata, "distribution", lambda _name: _Dist(without_commit))
    monkeypatch.setattr(stack, "_git_remote_commit", _remote(commit))
    assert stack._direct_reference_is_installed(req, "triton_kernels") is False

    other_branch = {**recorded, "vcs_info": {**recorded["vcs_info"], "requested_revision": "main"}}
    monkeypatch.setattr(importlib.metadata, "distribution", lambda _name: _Dist(other_branch))
    assert stack._direct_reference_is_installed(req, "triton_kernels") is False


def test_the_triton_step_keeps_a_current_build_even_on_a_full_pass(monkeypatch, capsys) -> None:
    """With no usable recorded evidence `_skip_step` says "run"; the step still asks the
    remote and keeps the resident build when the branch has not moved (or cannot be
    asked), and installs only when it has. Nothing is asked twice."""
    installs: list = []
    recorded: list = []
    asked: list = []
    monkeypatch.setattr(stack, "_has_working_git", lambda: True)
    monkeypatch.setattr(stack, "pip_install", lambda *a, **k: installs.append((a, k)))
    monkeypatch.setattr(stack, "_record_step", lambda key, outcome: recorded.append((key, outcome)))
    monkeypatch.setattr(stack, "_progress", lambda *_a, **_k: None)
    payload_intact = {"value": True}
    monkeypatch.setattr(stack, "_payload_recorded_intact", lambda dist: payload_intact["value"])
    monkeypatch.setattr(stack, "_full_deps_requested", lambda: False)

    def _skip(
        req,
        label,
        *,
        no_deps,
        constrain,
        extra_check = None,
    ):
        return False

    monkeypatch.setattr(stack, "_skip_step", _skip)

    def _current(answer):
        def _ask(req, dist):
            asked.append((req.name, dist))
            return answer

        return _ask

    monkeypatch.setattr(stack, "_direct_reference_is_installed", _current(True))
    stack._triton_kernels_step()
    assert installs == []
    assert asked == [("triton-kernels.txt", "triton_kernels")]
    assert recorded and recorded[-1][1] == "skipped"
    assert "kept" in capsys.readouterr().out

    asked.clear()
    monkeypatch.setattr(stack, "_direct_reference_is_installed", _current(False))
    stack._triton_kernels_step()
    assert len(installs) == 1 and installs[0][0][0] == "Installing triton kernels"
    assert (
        installs[0][1]["req"].name == "triton-kernels.txt" and installs[0][1]["constrain"] is False
    )
    assert asked == [("triton-kernels.txt", "triton_kernels")]

    installs.clear()
    asked.clear()

    def _skip_asking(
        req,
        label,
        *,
        no_deps,
        constrain,
        extra_check = None,
    ):
        return bool(extra_check())

    monkeypatch.setattr(stack, "_skip_step", _skip_asking)
    monkeypatch.setattr(stack, "_direct_reference_is_installed", _current(True))
    stack._triton_kernels_step()
    assert installs == [] and len(asked) == 1

    asked.clear()
    monkeypatch.setattr(stack, "_has_working_git", lambda: False)
    stack._triton_kernels_step()
    assert installs == [] and asked == []

    monkeypatch.setattr(stack, "_has_working_git", lambda: True)
    monkeypatch.setattr(stack, "_skip_step", _skip)
    monkeypatch.setattr(stack, "_direct_reference_is_installed", _current(True))
    payload_intact["value"] = False
    stack._triton_kernels_step()
    assert len(installs) == 1 and installs[0][0][0] == "Installing triton kernels"
    installs.clear()
    payload_intact["value"] = True
    monkeypatch.setattr(stack, "_full_deps_requested", lambda: True)
    stack._triton_kernels_step()
    assert len(installs) == 1


def test_the_remote_commit_probe_reads_ls_remote_and_fails_closed(monkeypatch) -> None:
    """`git ls-remote -- URL REF` answers `sha<TAB>ref` rows; a peeled tag wins over the tag
    object and a branch over a tag, and any failure (no git, non-zero exit, timeout, no
    rows) answers None so the caller keeps the resident build."""
    import subprocess as _sp

    calls: list = []

    class _Done:
        def __init__(self, rc, out):
            self.returncode = rc
            self.stdout = out

    def _fake_run(argv, **kwargs):
        calls.append((list(argv), kwargs))
        return _fake_run.answer

    monkeypatch.setattr(stack.shutil, "which", lambda _name: "/usr/bin/git")
    monkeypatch.setattr(stack.subprocess, "run", _fake_run)

    _fake_run.answer = _Done(
        0, "aaaa000000000000000000000000000000000001\trefs/heads/release/3.6.x\n"
    )
    assert stack._git_remote_commit("https://example.invalid/t.git", "release/3.6.x") == (
        "aaaa000000000000000000000000000000000001"
    )
    argv, kwargs = calls[-1]
    assert argv[:3] == ["/usr/bin/git", "ls-remote", "--"]
    assert argv[3:] == ["https://example.invalid/t.git", "release/3.6.x", "release/3.6.x^{}"]
    assert kwargs["env"]["GIT_TERMINAL_PROMPT"] == "0"

    _fake_run.answer = _Done(
        0,
        "bbbb000000000000000000000000000000000002\trefs/tags/v1\n"
        "cccc000000000000000000000000000000000003\trefs/tags/v1^{}\n",
    )
    assert stack._git_remote_commit("https://example.invalid/t.git", "v1") == (
        "cccc000000000000000000000000000000000003"
    )

    _fake_run.answer = _Done(128, "")
    assert stack._git_remote_commit("https://example.invalid/t.git", "release/3.6.x") is None
    _fake_run.answer = _Done(0, "")
    assert stack._git_remote_commit("https://example.invalid/t.git", "release/3.6.x") is None

    def _timeout(argv, **kwargs):
        raise _sp.TimeoutExpired(argv, 1)

    monkeypatch.setattr(stack.subprocess, "run", _timeout)
    assert stack._git_remote_commit("https://example.invalid/t.git", "release/3.6.x") is None
    monkeypatch.setattr(stack.shutil, "which", lambda _name: None)
    assert stack._git_remote_commit("https://example.invalid/t.git", "release/3.6.x") is None


@pytest.mark.skipif(shutil.which("git") is None, reason = "needs git")
def test_the_remote_commit_probe_peels_a_real_annotated_tag(tmp_path) -> None:
    """Real git omits the `^{}` row unless asked, so the tag object (not a commit) leaked through."""
    import subprocess as _sp

    env = dict(os.environ, GIT_AUTHOR_NAME = "t", GIT_AUTHOR_EMAIL = "t@t")
    env.update(GIT_COMMITTER_NAME = "t", GIT_COMMITTER_EMAIL = "t@t")

    def git(*args):
        argv = ["git", "-C", str(tmp_path), *args]
        return _sp.run(argv, check = True, capture_output = True, text = True, env = env).stdout.strip()

    git("init", "-q")
    git("commit", "-q", "--allow-empty", "-m", "c")
    git("tag", "-a", "v1", "-m", "annotated")
    commit = git("rev-parse", "HEAD")
    assert git("rev-parse", "v1") != commit
    assert stack._git_remote_commit(tmp_path.as_uri(), "v1") == commit
    branch = git("symbolic-ref", "--short", "HEAD")
    assert stack._git_remote_commit(tmp_path.as_uri(), branch) == commit
    # A same-named branch still wins over the tag, as pip and uv resolve it.
    git("commit", "-q", "--allow-empty", "-m", "d")
    git("branch", "v1")
    assert stack._git_remote_commit(tmp_path.as_uri(), "v1") == git("rev-parse", "HEAD")


@pytest.mark.parametrize("name", ["UV_CONSTRAINT", "PIP_CONSTRAINT", "PIP_NO_DEPS", "UV_NO_DEPS"])
def test_a_caller_supplied_resolver_input_forces_a_full_pass(monkeypatch, manifest, name) -> None:
    """Additive constraints change which versions a step installs, and PIP_NO_DEPS makes
    a with-deps step leave dependencies out; no digest the gate keeps sees either."""
    payload, _req_root = manifest
    monkeypatch.setattr(stack.install_manifest, "read_manifest", lambda *a, **k: dict(payload))
    for other in stack._FOREIGN_RESOLVER_ENV:
        monkeypatch.delenv(other, raising = False)
    assert _plan() is not None
    monkeypatch.setenv(name, "1" if "NO_DEPS" in name else "/tmp/constraints.txt")
    assert _plan() is None
    monkeypatch.setenv(name, "   ")
    assert _plan() is not None


def test_no_closure_record_is_kept_under_a_callers_no_deps(monkeypatch) -> None:
    """A dependency PIP_NO_DEPS left out is not a known conflict; carrying it forward
    would skip the step that installs it on the next run."""
    monkeypatch.setenv("PIP_NO_DEPS", "1")
    assert stack._closure_record() == {}


def test_no_closure_record_is_kept_under_a_callers_uv_override(monkeypatch, gated) -> None:
    """Unmet requirements under a uv override are the override's doing, so no closure record is kept."""
    _payload, req_root = gated
    monkeypatch.setattr(stack, "_AUDITED_STEPS", {"studio.txt": req_root / "studio.txt"})
    monkeypatch.setattr(stack, "_STEP_RESULTS", {"studio.txt": "ran"})
    monkeypatch.setattr(
        stack.install_manifest, "closure_unmet_requirements", lambda *a, **k: ["click 8.5.0"]
    )
    assert stack._closure_record() == {"studio.txt": ["click 8.5.0"]}
    foreign = req_root / "my-overrides.txt"
    foreign.write_text("click==8.5.0\n", encoding = "utf-8")
    monkeypatch.setenv("UV_OVERRIDE", str(foreign))
    assert stack._closure_record() == {}
    monkeypatch.setenv("UV_OVERRIDE", str(stack._MLX_OVERRIDES))
    assert stack._closure_record() == {"studio.txt": ["click 8.5.0"]}


def test_a_caller_supplied_uv_override_forces_a_full_pass(monkeypatch, manifest) -> None:
    """uv applies UV_OVERRIDE to every step and its versions replace requirements outright; the gate
    digests only the bundled macOS file, so a caller's own file is invisible."""
    payload, req_root = manifest
    monkeypatch.setattr(stack.install_manifest, "read_manifest", lambda *a, **k: dict(payload))
    foreign = req_root / "my-overrides.txt"
    foreign.write_text("numpy==1.0\n", encoding = "utf-8")
    monkeypatch.setenv("UV_OVERRIDE", str(foreign))
    assert _plan() is None
    monkeypatch.setenv("UV_OVERRIDE", str(stack._MLX_OVERRIDES))
    assert _plan() is not None
    monkeypatch.setenv("UV_OVERRIDE", stack._uv_safe_path(stack._MLX_OVERRIDES))
    assert _plan() is not None
    monkeypatch.delenv("UV_OVERRIDE")
    assert _plan() is not None


def test_userinfo_in_a_git_url_is_not_mistaken_for_a_ref(tmp_path) -> None:
    req = tmp_path / "t.txt"
    req.write_text("pkg @ git+ssh://[email protected]/repo.git\n", encoding = "utf-8")
    assert stack._direct_reference_in_requirements(req) == (
        "ssh://[email protected]/repo.git",
        "",
        "",
    )


def test_the_shipped_triton_requirement_still_parses() -> None:
    parsed = stack._direct_reference_in_requirements(
        REPO_ROOT / "studio" / "backend" / "requirements" / "triton-kernels.txt"
    )
    assert parsed is not None
    url, revision, subdirectory = parsed
    assert url.startswith("https://") and revision and subdirectory


def test_a_plugin_digest_is_stable_and_content_addressed(tmp_path) -> None:
    """A directory listing has no order, so a digest that depended on one would differ
    between two byte-identical trees and reinstall both seed plugins every update."""
    first = tmp_path / "a"
    (first / "src").mkdir(parents = True)
    (first / "pyproject.toml").write_text("name = 'x'\n", encoding = "utf-8")
    (first / "src" / "mod.py").write_text("VALUE = 1\n", encoding = "utf-8")
    second = tmp_path / "b"
    (second / "src").mkdir(parents = True)
    (second / "src" / "mod.py").write_text("VALUE = 1\n", encoding = "utf-8")
    (second / "pyproject.toml").write_text("name = 'x'\n", encoding = "utf-8")

    assert stack._local_plugin_digest(first) == stack._local_plugin_digest(second)
    (second / "src" / "mod.py").write_text("VALUE = 2\n", encoding = "utf-8")
    assert stack._local_plugin_digest(first) != stack._local_plugin_digest(second)


@pytest.mark.skipif(os.name == "nt", reason = "Windows filenames are UTF-16, not bytes")
def test_a_filename_that_is_not_utf_8_still_digests(tmp_path) -> None:
    """POSIX filenames are bytes. A stray one beside the sources -- a download, an editor
    backup -- used to raise UnicodeEncodeError out of the digest and end the update."""
    plugin = tmp_path / "p"
    plugin.mkdir()
    (plugin / "ok.py").write_text("x\n", encoding = "utf-8")
    odd = os.path.join(str(plugin), b"\xff.txt".decode("utf-8", "surrogateescape"))
    try:
        with open(odd, "wb") as handle:
            handle.write(b"x")
    except OSError:
        # APFS and other filesystems enforce UTF-8 names, so there is nothing to test here.
        pytest.skip("this filesystem refuses filenames that are not UTF-8")
    digest = stack._local_plugin_digest(plugin)
    assert digest and stack._local_plugin_digest(plugin) == digest


def test_a_renamed_file_changes_the_plugin_digest(tmp_path) -> None:
    """Path and bytes both, so moving a file between two names is not a no-op."""
    plugin = tmp_path / "p"
    plugin.mkdir()
    (plugin / "one.py").write_text("x\n", encoding = "utf-8")
    before = stack._local_plugin_digest(plugin)
    (plugin / "one.py").rename(plugin / "two.py")
    assert stack._local_plugin_digest(plugin) != before


def test_what_a_build_writes_into_the_plugin_tree_does_not_move_its_digest(tmp_path) -> None:
    """Only the sources decide: build/ and egg-info written by an install must not move the digest."""
    plugin = tmp_path / "data-designer-unstructured-seed"
    (plugin / "src" / "pkg").mkdir(parents = True)
    (plugin / "pyproject.toml").write_text("name = 'x'\n", encoding = "utf-8")
    (plugin / "src" / "pkg" / "__init__.py").write_text("VALUE = 1\n", encoding = "utf-8")
    clean = stack._local_plugin_digest(plugin)

    (plugin / "build" / "lib" / "pkg").mkdir(parents = True)
    (plugin / "build" / "lib" / "pkg" / "__init__.py").write_text("VALUE = 1\n", encoding = "utf-8")
    (plugin / "src" / "pkg.egg-info").mkdir()
    (plugin / "src" / "pkg.egg-info" / "SOURCES.txt").write_text(
        "pyproject.toml\n", encoding = "utf-8"
    )
    (plugin / "src" / "pkg.egg-info" / "PKG-INFO").write_text("Name: x\n", encoding = "utf-8")
    (plugin / "src" / "pkg" / "__pycache__").mkdir()
    (plugin / "src" / "pkg" / "__pycache__" / "__init__.cpython-313.pyc").write_bytes(b"\x00")
    (plugin / "dist").mkdir()
    (plugin / "dist" / "x-0.1-py3-none-any.whl").write_bytes(b"PK")
    assert stack._local_plugin_digest(plugin) == clean

    (plugin / "src" / "pkg" / "__init__.py").write_text("VALUE = 2\n", encoding = "utf-8")
    assert stack._local_plugin_digest(plugin) != clean


def test_the_shipped_plugins_digest(tmp_path) -> None:
    for plugin in (stack.LOCAL_DD_UNSTRUCTURED_PLUGIN, stack.LOCAL_DD_GITHUB_PLUGIN):
        assert stack._local_plugin_digest(plugin)


def test_an_unreadable_plugin_has_no_digest(tmp_path) -> None:
    assert stack._local_plugin_digest(tmp_path / "gone") is None


def test_the_uv_probe_resolves_nothing(monkeypatch) -> None:
    """`uv pip install --dry-run pip` answered "can this uv address this interpreter"
    by resolving pip against the index -- one PyPI round trip on every installer run,
    and a hard failure on an offline host uv could have served from its cache."""
    seen: list[list[str]] = []

    class _Result:
        returncode = 0

    monkeypatch.setattr(stack.shutil, "which", lambda _name: "/usr/bin/uv")
    monkeypatch.setattr(stack.subprocess, "run", lambda cmd, **_k: (seen.append(cmd), _Result())[1])
    assert stack._bootstrap_uv() is True
    assert seen == [["uv", "pip", "freeze", "--python", sys.executable]]
    assert not any("--dry-run" in cmd for cmd in seen)
    assert not any("install" in cmd for cmd in seen)


def test_the_uv_probe_still_retries_with_system(monkeypatch) -> None:
    seen: list[list[str]] = []
    codes = iter([1, 0])

    class _Result:
        def __init__(self, code):
            self.returncode = code

    monkeypatch.setattr(stack.shutil, "which", lambda _name: "/usr/bin/uv")
    monkeypatch.setattr(
        stack.subprocess, "run", lambda cmd, **_k: (seen.append(cmd), _Result(next(codes)))[1]
    )
    monkeypatch.setattr(stack, "UV_NEEDS_SYSTEM", False)
    assert stack._bootstrap_uv() is True
    assert stack.UV_NEEDS_SYSTEM is True
    assert seen[1] == ["uv", "pip", "freeze", "--system"]


def test_a_broken_uv_still_falls_back_to_pip(monkeypatch) -> None:
    class _Result:
        returncode = 2

    monkeypatch.setattr(stack.shutil, "which", lambda _name: "/usr/bin/uv")
    monkeypatch.setattr(stack.subprocess, "run", lambda cmd, **_k: _Result())
    assert stack._bootstrap_uv() is False


def test_a_venv_that_already_has_pip_does_not_reinstall_it(monkeypatch) -> None:
    monkeypatch.setattr(
        stack.subprocess, "run", lambda cmd, **_k: types.SimpleNamespace(returncode = 0)
    )
    monkeypatch.setattr(stack, "_installed_distribution_version", lambda _n: "26.2.2")
    assert stack._venv_pip_is_usable() is True
    # Below the trust floor's pip on 3.10+, so the bootstrap runs.
    monkeypatch.setattr(stack, "_installed_distribution_version", lambda _n: "24.2")
    assert stack._venv_pip_is_usable() is (sys.version_info < (3, 10))
    monkeypatch.setattr(stack, "_installed_distribution_version", lambda _n: "22.0.4")
    assert stack._venv_pip_is_usable() is False
    monkeypatch.setattr(stack, "_installed_distribution_version", lambda _n: None)
    assert stack._venv_pip_is_usable() is False
    monkeypatch.setattr(stack, "_installed_distribution_version", lambda _n: "not-a-version")
    assert stack._venv_pip_is_usable() is False


def test_a_fresh_uv_venv_still_bootstraps(monkeypatch) -> None:
    """uv venvs omit pip entirely, and that is the case this step exists for."""
    monkeypatch.setattr(stack.importlib.util, "find_spec", lambda _n: None)
    assert stack._venv_pip_is_usable() is False


def test_a_pip_that_cannot_run_is_bootstrapped_again(monkeypatch) -> None:
    """Metadata survives a pip whose __main__.py is gone; `python -m pip` does not."""
    monkeypatch.setattr(stack, "_installed_distribution_version", lambda _n: "26.2.2")
    seen: list[list[str]] = []

    def broken(cmd, **_k):
        seen.append(list(cmd))
        return types.SimpleNamespace(returncode = 1)

    monkeypatch.setattr(stack.subprocess, "run", broken)
    assert stack._venv_pip_is_usable() is False
    assert seen and seen[0][1:] == ["-m", "pip", "--version"]

    def hangs(cmd, **kw):
        raise stack.subprocess.TimeoutExpired(cmd, kw.get("timeout", 60))

    monkeypatch.setattr(stack.subprocess, "run", hangs)
    assert stack._venv_pip_is_usable() is False


def test_the_mlx_stack_is_current_only_when_all_four_hold(monkeypatch) -> None:
    versions = {"mlx": "0.32.4", "mlx-metal": "0.32.4", "mlx-lm": "0.32.2", "mlx-vlm": "0.5.0"}
    monkeypatch.setattr(stack, "_installed_distribution_version", lambda name: versions.get(name))
    monkeypatch.setattr(stack, "_mlx_closure_unmet", lambda: False)
    monkeypatch.setattr(stack, "_mlx_lm_spec_for_installed_zoo", lambda: stack._MLX_LM_SPEC)
    assert stack._mlx_stack_is_current() is True
    for lm in ("0.31.3", "0.32.2"):  # either end of the range, as Python 3.10 and 3.11+ resolve
        monkeypatch.setattr(
            stack,
            "_installed_distribution_version",
            lambda n, v = {**versions, "mlx-lm": lm}: v.get(n),
        )
        assert stack._mlx_stack_is_current() is True, lm
    for name, wrong in (
        ("mlx", "0.32.0"),
        ("mlx-metal", None),
        ("mlx-lm", "0.31.2"),
        ("mlx-lm", "0.32.3"),
        ("mlx-lm", None),
        ("mlx-vlm", "0.8.0"),
        ("mlx-vlm", None),
    ):
        broken = dict(versions)
        broken[name] = wrong
        monkeypatch.setattr(stack, "_installed_distribution_version", lambda n, b = broken: b.get(n))
        assert stack._mlx_stack_is_current() is False, name


def test_a_satisfied_mlx_pin_with_a_broken_closure_is_not_current(monkeypatch, tmp_path) -> None:
    """This step installs WITH dependencies, so it is what repairs an mlx-vlm whose own
    miniaudio or mlx-audio is gone. Versions alone would skip that repair."""
    versions = {"mlx": "0.32.4", "mlx-metal": "0.32.4", "mlx-lm": "0.32.2", "mlx-vlm": "0.5.0"}
    monkeypatch.setattr(stack, "_installed_distribution_version", lambda name: versions.get(name))
    monkeypatch.setattr(stack, "_mlx_closure_unmet", lambda: True)
    assert stack._mlx_stack_is_current() is False


def test_the_mlx_audit_does_not_fight_the_bundled_override(monkeypatch) -> None:
    """An override REPLACES every requirement on the package it names, so the version the
    installer leaves behind is the override's, not the one mlx-vlm's metadata asks for. Read
    raw, that disagreement is permanent and the MLX step would run on every update forever."""
    monkeypatch.setattr(stack, "_installed_index", lambda: {})
    names = stack._overridden_project_names()
    assert {"transformers", "anyio", "huggingface-hub"} <= names

    monkeypatch.setattr(
        stack.install_manifest,
        "closure_unmet_requirements",
        lambda *a, **k: ["transformers 5.5.0", "anyio 4.13.0"],
    )
    assert stack._mlx_closure_unmet() is False
    monkeypatch.setattr(
        stack.install_manifest, "closure_unmet_requirements", lambda *a, **k: ["transformers"]
    )
    assert stack._mlx_closure_unmet() is True
    monkeypatch.setattr(
        stack.install_manifest,
        "closure_unmet_requirements",
        lambda *a, **k: ["transformers 5.5.0", "miniaudio 1.0"],
    )
    assert stack._mlx_closure_unmet() is True


def test_the_mlx_closure_audit_reads_the_pins_and_cleans_up(monkeypatch, tmp_path) -> None:
    seen: list[str] = []
    written: list[pathlib.Path] = []

    def _closure(
        req,
        _index = None,
        **_kwargs,
    ):
        seen.append(req.read_text(encoding = "utf-8"))
        assert req.exists()
        written.append(pathlib.Path(req))
        return ["miniaudio"]

    # mkstemp defaults to the shared temp dir; isolate it so other xdist workers' files are not seen.
    monkeypatch.setattr(tempfile, "tempdir", str(tmp_path))
    monkeypatch.setattr(stack.install_manifest, "closure_unmet_requirements", _closure)
    monkeypatch.setattr(stack, "_installed_index", lambda: {})
    assert stack._mlx_closure_unmet() is True
    assert seen and all(
        spec in seen[0] for spec in [*stack._MLX_PINS, stack._MLX_LM_SPEC, stack._MLX_VLM_SPEC]
    )
    assert not list(tmp_path.glob("unsloth-mlx-*.txt"))
    assert written and written[0].parent == tmp_path
    assert not written[0].exists()

    def _raises(*_a, **_k):
        raise RuntimeError("metadata unreadable")

    monkeypatch.setattr(stack.install_manifest, "closure_unmet_requirements", _raises)
    assert stack._mlx_closure_unmet() is True


def test_the_mlx_pins_match_the_runtime_repair() -> None:
    """One stack, two callers. The self-heal at startup reinstalls whatever this
    installed, so a pin that drifts here is a repair loop there."""
    names = {spec.partition("==")[0] for spec in stack._MLX_PINS} | {"mlx-lm", "mlx-vlm"}
    assert set(stack._MLX_NAMES) == names
    assert stack._MLX_VLM_SPEC.startswith("mlx-vlm")


@pytest.mark.parametrize(
    "spec,installed,expected",
    [
        ("torchcodec==0.8.0", "0.8.0", True),
        ("torchcodec==0.8.0", "0.8.0+cu130", True),
        ("torchcodec==0.8.0", "0.7.0", False),
        ("torchcodec>=0.7,<0.9", "0.8.0+cpu", True),
        ("torchcodec>=0.7,<0.9", "0.9.1", False),
        ("torchcodec==0.8.0", "", False),
    ],
)
def test_a_resident_codec_inside_the_window_needs_no_install(spec, installed, expected) -> None:
    """The local tag is ignored on purpose, since provenance is the caller's separate question, and
    a +cu130 suffix would put a version outside a PyPI-shaped specifier it satisfies."""
    assert stack._codec_spec_is_satisfied(spec, installed) is expected


def test_the_pip_fallback_never_names_one_project_twice() -> None:
    """pip refuses `mlx==0.32.3 mlx` outright with "Double requirement given", which
    would fail the very step the fallback exists to rescue."""
    cmd = stack._build_pip_cmd(
        (
            "--upgrade-package",
            "mlx",
            "--upgrade-package",
            "mlx-vlm",
            "mlx==0.32.3",
            "mlx-vlm>=0.4.4,<=0.7.12",
        )
    )
    assert "--upgrade" in cmd and "--upgrade-package" not in cmd
    assert cmd.count("mlx") == 0 and cmd.count("mlx-vlm") == 0
    assert "mlx==0.32.3" in cmd and "mlx-vlm>=0.4.4,<=0.7.12" in cmd


def test_a_package_named_only_by_the_flag_is_still_passed() -> None:
    """pip would otherwise upgrade nothing at all."""
    cmd = stack._build_pip_cmd(("--upgrade-package", "future-pkg", "other"))
    assert "future-pkg" in cmd and "other" in cmd


def test_every_install_entry_point_is_counted() -> None:
    """Each install entry point must bump the counter, or pip check is skipped on a changed venv."""
    source = STACK_PATH.read_text(encoding = "utf-8")
    tree = ast.parse(source)
    counted = {
        "_pip_install_once",
        "pip_install_try",
        "_uninstall_distribution",
        "_purge_recordless_distributions",
        "_repair_duplicate_core_metadata",
    }
    for node in ast.walk(tree):
        if isinstance(node, ast.FunctionDef) and node.name in counted:
            body = ast.dump(node)
            assert "_count_install_action" in body, node.name
            counted.discard(node.name)
    assert not counted, f"install entry points are gone: {counted}"


@pytest.fixture
def counting(monkeypatch):
    """A zeroed counter and a constraint answer that is already cached against it."""
    monkeypatch.setattr(stack, "_INSTALL_ACTIONS", 0)
    monkeypatch.setattr(stack, "_CONSTRAINTS_CACHE", None)
    answers = iter([["numpy"], [], [], []])
    monkeypatch.setattr(
        stack.install_manifest, "violated_constraints", lambda *a, **k: next(answers)
    )
    monkeypatch.setattr(stack, "_safe_print", lambda *a, **k: None)
    monkeypatch.setattr(stack, "_step", lambda *a, **k: None)
    assert stack._violated_constraints() == ["numpy"]
    return monkeypatch


def _site_with_recordless_dist(monkeypatch, tmp_path):
    site = tmp_path / "site-packages"
    (site / "ghost-1.0.dist-info").mkdir(parents = True)
    monkeypatch.setattr(stack.sysconfig, "get_path", lambda name: str(site))
    return site


_PIP_REFUSED = "Cannot uninstall ghost 1.0, RECORD file not found: no RECORD file was found"


def test_purging_a_half_written_record_counts_as_an_install_action(counting, tmp_path) -> None:
    """Purging a dist-info pip was reading must count as an install action, or a constraint answer
    cached before it would let a gated step skip on stale evidence."""
    _site_with_recordless_dist(counting, tmp_path)
    assert stack._purge_recordless_distributions(_PIP_REFUSED) == ["ghost-1.0.dist-info"]
    assert stack._INSTALL_ACTIONS == 1
    assert stack._violated_constraints() == []


def test_a_purge_that_deletes_nothing_leaves_the_cache_alone(counting, tmp_path) -> None:
    """The count sits at the rmtree, not the top of the function, because pip check is gated on the
    same counter and a spurious increment forces a full metadata resolve on every no-op update."""
    site = _site_with_recordless_dist(counting, tmp_path)
    assert stack._purge_recordless_distributions("") == []
    assert stack._purge_recordless_distributions("some unrelated pip failure") == []
    (site / "ghost-1.0.dist-info" / "RECORD").write_text("", encoding = "utf-8")
    assert stack._purge_recordless_distributions(_PIP_REFUSED) == []
    assert stack._INSTALL_ACTIONS == 0
    assert stack._violated_constraints() == ["numpy"], "the cached answer was discarded"


class _ScriptedVersions:
    """installed_versions(), draining a scripted sequence of record counts."""

    def __init__(self, counts) -> None:
        self.counts = list(counts)

    def __call__(self, name, *args, **kwargs):
        count = self.counts.pop(0) if len(self.counts) > 1 else self.counts[0]
        return ["1.0"] * count


def _metadata_repair_stubs(
    monkeypatch,
    counts,
    *,
    invalid = (),
):
    monkeypatch.setattr(stack.install_manifest, "installed_versions", _ScriptedVersions(counts))
    monkeypatch.setattr(stack.install_manifest, "pip_backup_metadata_paths", lambda *a, **k: [])
    monkeypatch.setattr(
        stack.install_manifest, "invalid_metadata_paths", lambda *a, **k: list(invalid)
    )
    monkeypatch.setattr(
        stack.install_manifest, "installed_version_probe", lambda *a, **k: ("1.0", False)
    )
    monkeypatch.setattr(stack, "_rewrite_minimal_metadata", lambda path, name: True)
    monkeypatch.setattr(stack, "_stage_replacement", lambda name: "/staged")
    monkeypatch.setattr(stack, "_run_ok", lambda label, cmd: True)
    monkeypatch.setattr(stack, "pip_install_try", lambda *a, **k: True)


def test_removing_a_duplicate_metadata_record_counts_as_an_install_action(counting) -> None:
    """The uninstall loop goes through _run_ok, not _uninstall_distribution, so it was
    the one removal path the counter never saw."""
    _metadata_repair_stubs(counting, [2, 1, 0])
    assert stack._repair_duplicate_core_metadata(("unsloth",)) is True
    assert stack._INSTALL_ACTIONS == 2, "one per pip uninstall, as _uninstall_distribution"
    assert stack._violated_constraints() == []


def test_rewriting_unreadable_metadata_counts_even_if_the_repair_then_aborts(
    counting, tmp_path
) -> None:
    """The rewrite happens before anything is staged and is not undone by returning
    False: what importlib.metadata reports has already changed."""
    _metadata_repair_stubs(counting, [2, 0], invalid = [str(tmp_path)])
    assert stack._repair_duplicate_core_metadata(("unsloth",)) is False
    assert stack._INSTALL_ACTIONS == 1
    assert stack._violated_constraints() == []


def test_a_repair_with_nothing_to_repair_leaves_the_cache_alone(counting) -> None:
    """One readable record each and no damage: both repairs are pure inspection, and
    an update that does nothing must not pay for a `pip check` because they ran."""
    _metadata_repair_stubs(counting, [1])
    monkeypatch = counting
    monkeypatch.setattr(stack.install_manifest, "damaged_payload_files", lambda *a, **k: [])
    assert stack._repair_duplicate_core_metadata(("unsloth", "unsloth-zoo")) is True
    assert stack._repair_damaged_core_payload(("unsloth", "unsloth-zoo")) is True
    assert stack._INSTALL_ACTIONS == 0
    assert stack._violated_constraints() == ["numpy"], "the cached answer was discarded"


def test_the_pass_state_is_reset_per_call() -> None:
    """The suites call install_python_stack() several times in one interpreter, and a
    counter that survived would make the second call skip what the first installed."""
    source = STACK_PATH.read_text(encoding = "utf-8")
    entry = source[source.index("def install_python_stack() -> int:") :]
    head = entry[: entry.index("# --package installs")]
    for name in ("_INSTALL_ACTIONS = 0", "_PASS_EVIDENCE = None", "_STEP_RESULTS.clear()"):
        assert name in head, name


def test_the_plan_is_read_before_the_manifest_is_dropped() -> None:
    """remove_manifest deletes the only copy of what the last run did."""
    source = STACK_PATH.read_text(encoding = "utf-8")
    plan = source.index("_PASS_EVIDENCE = _plan_pass(")
    drop = source.index("install_manifest.remove_manifest()")
    assert plan < drop


class _FakePatchModule:
    """Stands in for requirements/single-env/patch_metadata.py."""

    TARGETS = ("data-designer",)
    PATCHES = ((re.compile(r"^Requires-Dist: huggingface-hub<2,>=1\.0\.1$", re.MULTILINE), "x"),)

    def __init__(
        self,
        path,
        *,
        raise_on_lookup = False,
        raise_on_main = False,
    ):
        self._path = path
        self._raise_on_lookup = raise_on_lookup
        self._raise_on_main = raise_on_main
        self.main_calls = 0

    def metadata_path(self, _name):
        if self._raise_on_lookup:
            raise RuntimeError("distribution metadata is unreadable")
        return self._path

    def main(self):
        self.main_calls += 1
        print("single-env metadata patch: checked=1, changed=1")
        if self._raise_on_main:
            raise RuntimeError("cannot patch in process")
        return 0


PATCHED = "Requires-Dist: huggingface-hub<2,>=0.34.0\n"
UNPATCHED = "Requires-Dist: huggingface-hub<2,>=1.0.1\n"


def _patch_module(
    monkeypatch,
    tmp_path,
    text = PATCHED,
    **kwargs,
):
    metadata = tmp_path / "METADATA"
    if text is not None:
        metadata.write_text(text, encoding = "utf-8")
    fake = _FakePatchModule(metadata if text is not None else None, **kwargs)
    monkeypatch.setattr(stack, "SINGLE_ENV", tmp_path)
    # Cached in sys.modules after the first pass, so the second call in one interpreter sees it too.
    monkeypatch.setitem(sys.modules, "patch_metadata", fake)
    return fake


def test_a_settled_install_does_not_re_run_the_metadata_patch(monkeypatch, tmp_path) -> None:
    _patch_module(monkeypatch, tmp_path, PATCHED)
    assert stack._patch_metadata_is_pending() is False


def test_an_unpatched_metadata_file_is_still_pending(monkeypatch, tmp_path) -> None:
    _patch_module(monkeypatch, tmp_path, UNPATCHED)
    assert stack._patch_metadata_is_pending() is True


def test_a_distribution_that_is_not_installed_needs_no_patch(monkeypatch, tmp_path) -> None:
    _patch_module(monkeypatch, tmp_path, None)
    assert stack._patch_metadata_is_pending() is False


@pytest.mark.parametrize("kwargs", [{"raise_on_lookup": True}])
def test_anything_it_cannot_answer_runs_the_patch(monkeypatch, tmp_path, kwargs) -> None:
    """Unknown means do the work: this replaces an unconditional run, so the failure
    mode of the question must be the old behaviour, not a skip."""
    _patch_module(monkeypatch, tmp_path, PATCHED, **kwargs)
    assert stack._patch_metadata_is_pending() is True


def test_an_unimportable_patch_module_runs_the_patch(monkeypatch, tmp_path) -> None:
    monkeypatch.setattr(stack, "SINGLE_ENV", tmp_path / "gone")
    monkeypatch.delitem(sys.modules, "patch_metadata", raising = False)
    assert stack._patch_metadata_is_pending() is True


def test_the_patch_applies_in_process(monkeypatch, tmp_path) -> None:
    fake = _patch_module(monkeypatch, tmp_path, UNPATCHED)
    ran = []
    monkeypatch.setattr(stack, "run", lambda *a, **k: ran.append(a))
    stack._run_patch_metadata()
    assert fake.main_calls == 1
    assert ran == []


def test_the_in_process_patch_does_not_print_into_the_progress_line(
    monkeypatch, tmp_path, capsys
) -> None:
    """The script prints its tally, and the subprocess path it replaces captured that.
    In process it would land in the middle of the progress bar."""
    _patch_module(monkeypatch, tmp_path, UNPATCHED)
    monkeypatch.setattr(stack, "run", lambda *a, **k: None)
    monkeypatch.setattr(stack, "VERBOSE", False)
    stack._run_patch_metadata()
    assert capsys.readouterr().out == ""
    monkeypatch.setattr(stack, "VERBOSE", True)
    stack._run_patch_metadata()
    assert "checked=1, changed=1" in capsys.readouterr().out


def test_the_patch_still_falls_back_to_the_subprocess(monkeypatch, tmp_path) -> None:
    """It is a supported standalone entry point, and an import failure inside the
    installer must not turn into a failed install."""
    fake = _patch_module(monkeypatch, tmp_path, UNPATCHED, raise_on_main = True)
    ran = []
    monkeypatch.setattr(stack, "run", lambda *a, **k: ran.append(a))
    stack._run_patch_metadata()
    assert fake.main_calls == 1
    assert len(ran) == 1 and str(tmp_path / "patch_metadata.py") in [str(x) for x in ran[0][1]]


@pytest.mark.parametrize("fn", ["_patch_metadata_is_pending", "_run_patch_metadata"])
def test_neither_helper_leaves_single_env_on_sys_path(monkeypatch, tmp_path, fn) -> None:
    """sys.path.insert(0, SINGLE_ENV) that outlives the call shadows stdlib names for
    the rest of the install."""
    _patch_module(monkeypatch, tmp_path, UNPATCHED)
    monkeypatch.setattr(stack, "run", lambda *a, **k: None)
    before = list(sys.path)
    getattr(stack, fn)()
    assert sys.path == before


def test_the_metadata_patch_still_runs_whenever_data_designer_did() -> None:
    """The pending scan reads the METADATA of packages the data-designer steps just
    wrote, so a fresh install must not be gated on it at all."""
    source = STACK_PATH.read_text(encoding = "utf-8")
    assert "_finalize_ran = _dd_deps_ran or _dd_ran or _patch_metadata_is_pending()" in source


def test_pip_check_is_gated_on_this_pass_having_changed_something() -> None:
    source = STACK_PATH.read_text(encoding = "utf-8")
    gate = source.index('_pip_check_ok = (_PASS_EVIDENCE or {}).get("pip_check_ok")')
    tail = source[gate : gate + 400]
    assert "if _INSTALL_ACTIONS > 0 or _pip_check_ok is not True:" in tail
    assert '"pip_check_ok": _pip_check_ok,' in source


class _FakeSubprocess:
    def __init__(self, stdout = "[]"):
        self.calls = 0
        self._stdout = stdout

    def run(self, *args, **kwargs):
        self.calls += 1
        return type("R", (), {"stdout": self._stdout, "stderr": "", "returncode": 0})()


@pytest.fixture
def mlx(monkeypatch):
    fake = _FakeSubprocess()
    monkeypatch.setattr(stack, "subprocess", fake)
    monkeypatch.setattr(stack, "_installed_distribution_version", lambda _n: "0.4.5")
    steps: list[tuple[str, str]] = []
    monkeypatch.setattr(stack, "_step", lambda label, value, *a: steps.append((label, value)))
    written: list[dict] = []
    monkeypatch.setattr(
        stack.install_manifest,
        "update_manifest",
        lambda **kw: written.append(kw.get("mlx_health")) or True,
    )
    healthy = {**stack._mlx_health_fingerprint(), "ok": True}
    monkeypatch.setattr(stack, "_PASS_EVIDENCE", {"mlx_health": healthy})
    monkeypatch.setattr(stack, "_mlx_payload_present", lambda: True)
    return fake, steps, written, healthy


def test_a_recorded_healthy_stack_is_not_re_probed(mlx) -> None:
    fake, steps, written, _ = mlx
    stack._report_mlx_stack_health(skipped = True)
    assert fake.calls == 0
    assert steps == [("mlx", "training stack ready")]
    assert written and written[0]["ok"] is True


def test_a_recorded_verdict_needs_the_payload_on_disk(mlx, monkeypatch) -> None:
    """Pins and interpreter survive a payload deleted after the pass; the recorded verdict
    does not describe a package whose files are gone, so the probe runs."""
    fake, steps, _written, _ = mlx
    monkeypatch.setattr(stack, "_mlx_payload_present", lambda: False)
    stack._report_mlx_stack_health(skipped = True)
    assert fake.calls == 1


def test_a_rebuilt_mlx_stack_is_always_probed(mlx) -> None:
    fake, steps, _written, _ = mlx
    stack._report_mlx_stack_health(skipped = False)
    assert fake.calls == 1


@pytest.mark.parametrize(
    "mutation",
    [
        {"ok": False},
        {"ok": None},
        {"pins": ["mlx==0.0.1"]},
        {"python": "39"},
        {"mlx_vlm": "0.4.4"},
        {
            "imports": {
                **{n: "0.4.5" for n in stack._MLX_IMPORTED_DEPENDENCIES},
                "transformers": "4.0.0",
            }
        },
        {"imports": None},
    ],
)
def test_a_verdict_that_no_longer_describes_this_install_is_re_probed(mlx, mutation) -> None:
    fake, _steps, _written, healthy = mlx
    stack._PASS_EVIDENCE = {"mlx_health": {**healthy, **mutation}}
    stack._report_mlx_stack_health(skipped = True)
    assert fake.calls == 1


def test_a_pass_that_installed_anything_re_probes(mlx, monkeypatch) -> None:
    """The probe imports transformers and tokenizers through mlx_lm; a later step of the
    same pass can move those with every MLX pin unchanged, so a recorded verdict only
    stands for a pass that installed nothing at all."""
    fake, _steps, _written, _ = mlx
    monkeypatch.setattr(stack, "_INSTALL_ACTIONS", 1)
    stack._report_mlx_stack_health(skipped = True)
    assert fake.calls == 1


def test_no_evidence_at_all_is_probed(mlx, monkeypatch) -> None:
    fake, _steps, _written, _ = mlx
    for evidence in (None, {}, {"mlx_health": "yes"}, {"mlx_health": {}}):
        fake.calls = 0
        monkeypatch.setattr(stack, "_PASS_EVIDENCE", evidence)
        stack._report_mlx_stack_health(skipped = True)
        assert fake.calls == 1, evidence


def test_the_fingerprint_names_everything_a_verdict_depends_on(monkeypatch) -> None:
    monkeypatch.setattr(stack, "_installed_distribution_version", lambda _n: "0.4.5")
    fingerprint = stack._mlx_health_fingerprint()
    # The installed zoo narrows the mlx-vlm range, so changing the zoo must invalidate the verdict.
    assert fingerprint["pins"] == list(stack._MLX_PINS) + [
        stack._mlx_lm_spec_for_installed_zoo(),
        stack._mlx_vlm_spec_for_installed_zoo(),
    ]
    assert fingerprint["pins"][-1].startswith(stack._MLX_VLM_SPEC)
    assert fingerprint["python"] == stack._installer_python_tag()
    assert fingerprint["imports"] == {n: "0.4.5" for n in stack._MLX_IMPORTED_DEPENDENCIES}
    assert {"transformers", "tokenizers", "numpy", "huggingface-hub"} <= set(fingerprint["imports"])
    # mlx-lm and mlx-vlm float inside ranges: the pin strings alone do not identify what is installed.
    assert fingerprint["mlx_lm"] == fingerprint["mlx_vlm"] == "0.4.5"
    monkeypatch.setattr(stack, "_installed_distribution_version", lambda _n: None)
    assert stack._mlx_health_fingerprint()["mlx_vlm"] == ""


def test_a_probe_verdict_is_recorded_for_next_time(mlx) -> None:
    fake, steps, written, _ = mlx
    stack._report_mlx_stack_health(skipped = False)
    assert written and written[0]["ok"] is True
    fake._stdout = '["mlx-lm is not importable"]'
    written.clear()
    stack._report_mlx_stack_health(skipped = False)
    assert written and written[0]["ok"] is False
    assert ("", "mlx-lm is not importable") in steps


def test_a_probe_that_cannot_answer_records_nothing(mlx) -> None:
    fake, _steps, written, _ = mlx
    fake._stdout = "null"
    stack._report_mlx_stack_health(skipped = False)
    assert written == []


def test_the_verdict_is_recorded_after_the_manifest_is_written() -> None:
    """The probe has a 180 s timeout. Writing through write_manifest would make a kill
    during it lose a finished install; update_manifest never creates one."""
    source = STACK_PATH.read_text(encoding = "utf-8")
    # rindex: the definition comes first in the file, the call site is what is ordered.
    assert source.index("install_manifest.write_manifest(") < source.rindex(
        "_report_mlx_stack_health("
    )
    for node in ast.walk(ast.parse(source)):
        if isinstance(node, ast.FunctionDef) and node.name == "_report_mlx_stack_health":
            called = {
                child.func.attr
                for child in ast.walk(node)
                if isinstance(child, ast.Call) and isinstance(child.func, ast.Attribute)
            }
            assert "write_manifest" not in called
            assert "update_manifest" in called
            break
    else:  # pragma: no cover - the function is the subject of this file
        raise AssertionError("_report_mlx_stack_health is gone")


def test_the_escape_hatch_reaches_the_pip_bootstrap_skip() -> None:
    """UNSLOTH_STUDIO_FULL_DEPS is the escape hatch users set when the install misbehaves, and the
    pip bootstrap skip is not gated on the manifest, so it must honour the flag."""
    source = STACK_PATH.read_text(encoding = "utf-8")
    assert "if not _full_deps_requested() and _venv_pip_is_usable():" in source


def _closure_index(**dists):
    """canonical name -> (version, Requires-Dist lines), as install_manifest builds it."""
    return {name.replace("_", "-").lower(): value for name, value in dists.items()}


def test_a_missing_transitive_dependency_is_not_satisfied(tmp_path) -> None:
    """The file's own lines stay true after a dependency of a dependency is removed.
    mammoth>=1.8.0 is satisfied by a mammoth whose cobble is gone, and importing it
    raises; the step that would have repaired that is the one being skipped."""
    req = tmp_path / "studio.txt"
    req.write_text("mammoth>=1.8.0\n", encoding = "utf-8")
    healthy = _closure_index(mammoth = ("1.12.1", ["cobble>=0.1.3"]), cobble = ("0.1.4", []))
    assert stack.install_manifest.unsatisfied_closure_requirement(req, healthy) is None
    damaged = _closure_index(mammoth = ("1.12.1", ["cobble>=0.1.3"]))
    assert stack.install_manifest.unsatisfied_closure_requirement(req, damaged) == "cobble"


def test_a_transitive_dependency_outside_its_window_is_not_satisfied(tmp_path) -> None:
    req = tmp_path / "studio.txt"
    req.write_text("cryptography\n", encoding = "utf-8")
    index = _closure_index(cryptography = ("46.0.3", ["cffi>=1.14"]), cffi = ("1.9.0", []))
    assert stack.install_manifest.unsatisfied_closure_requirement(req, index) == "cffi 1.9.0"


def test_every_unmet_closure_requirement_is_collected(tmp_path) -> None:
    """The gate needs the whole list, not the first hit: a step is skipped only when
    everything left unmet is on the record the last pass wrote."""
    req = tmp_path / "studio.txt"
    req.write_text("mammoth>=1.8.0\ncryptography\n", encoding = "utf-8")
    index = _closure_index(
        mammoth = ("1.12.1", ["cobble>=0.1.3"]),
        cryptography = ("46.0.3", ["cffi>=1.14"]),
        cffi = ("1.9.0", []),
    )
    unmet = stack.install_manifest.closure_unmet_requirements(req, index)
    assert sorted(unmet) == ["cffi 1.9.0", "cobble"]
    assert stack.install_manifest.unsatisfied_closure_requirement(req, index) in unmet


def test_a_conflict_the_last_pass_left_behind_does_not_run_the_step(monkeypatch, gated) -> None:
    """sqlfluff 3.x pins click<=8.3.0 and huggingface-hub 1.23+ needs click>=8.4.2, so
    the data-designer step's closure is unmet after every pass. The record the last
    pass wrote of exactly that lets the gate skip; a new unmet requirement still runs."""
    _payload, req_root = gated
    monkeypatch.setattr(
        stack.install_manifest, "closure_unmet_requirements", lambda *a, **k: ["click 8.5.0"]
    )
    monkeypatch.setattr(stack.install_manifest, "missing_requirements", lambda *a, **k: [])
    assert stack._requirements_satisfied(req_root / "studio.txt", no_deps = False) is False
    stack._PASS_EVIDENCE["known_unmet"] = {"studio.txt": ["click 8.5.0"]}
    assert stack._requirements_satisfied(req_root / "studio.txt", no_deps = False) is False
    stack._PASS_EVIDENCE["known_unmet_index"] = "not-the-installed-set"
    assert stack._requirements_satisfied(req_root / "studio.txt", no_deps = False) is False
    stack._PASS_EVIDENCE["known_unmet_index"] = stack._installed_index_digest()
    assert stack._PASS_EVIDENCE["known_unmet_index"]
    assert stack._requirements_satisfied(req_root / "studio.txt", no_deps = False) is True
    monkeypatch.setattr(
        stack.install_manifest,
        "closure_unmet_requirements",
        lambda *a, **k: ["click 8.5.0", "cobble"],
    )
    assert stack._requirements_satisfied(req_root / "studio.txt", no_deps = False) is False


def test_the_closure_record_never_carries_an_audit_failure(monkeypatch, gated) -> None:
    """A "<...>" entry means the audit could not run; recording it would let an
    unreadable environment skip the step next time."""
    _payload, req_root = gated
    monkeypatch.setattr(stack, "_AUDITED_STEPS", {"studio.txt": req_root / "studio.txt"})
    monkeypatch.setattr(stack, "_STEP_RESULTS", {"studio.txt": "ran"})
    monkeypatch.setattr(
        stack.install_manifest,
        "closure_unmet_requirements",
        lambda *a, **k: ["<metadata unreadable>", "click 8.5.0"],
    )
    assert stack._closure_record() == {"studio.txt": ["click 8.5.0"]}
    monkeypatch.setattr(stack, "_STEP_RESULTS", {"studio.txt": "skipped"})
    stack._PASS_EVIDENCE["known_unmet"] = {"studio.txt": ["click 8.3.0"]}
    assert stack._closure_record() == {"studio.txt": ["click 8.3.0"]}


def test_a_known_unmet_field_that_is_not_a_mapping_is_ignored(monkeypatch, gated) -> None:
    """Read from the manifest on disk and reached while write_manifest's arguments are
    being built, so a hand-edited value here used to abort a pass whose installs had all
    landed -- leaving the venv with no manifest at all."""
    _payload, req_root = gated
    monkeypatch.setattr(stack, "_AUDITED_STEPS", {"studio.txt": req_root / "studio.txt"})
    monkeypatch.setattr(stack, "_STEP_RESULTS", {"studio.txt": "skipped"})
    monkeypatch.setattr(
        stack.install_manifest, "closure_unmet_requirements", lambda *a, **k: ["click 8.3.0"]
    )
    for value in (["click 8.3.0"], "click", 7):
        stack._PASS_EVIDENCE["known_unmet"] = value
        assert stack._closure_record() == {}


def test_a_requirement_that_is_simply_absent_is_never_a_known_conflict(monkeypatch, gated) -> None:
    """An absent distribution is work this step performs, so it is never recorded as a known conflict."""
    _payload, req_root = gated
    monkeypatch.setattr(stack, "_AUDITED_STEPS", {"studio.txt": req_root / "studio.txt"})
    monkeypatch.setattr(stack, "_STEP_RESULTS", {"studio.txt": "ran"})
    monkeypatch.setattr(
        stack.install_manifest,
        "closure_unmet_requirements",
        lambda *a, **k: ["cobble", "click 8.3.0"],
    )
    assert stack._closure_record() == {"studio.txt": ["click 8.3.0"]}

    monkeypatch.setattr(stack, "_STEP_RESULTS", {"studio.txt": "skipped"})
    stack._PASS_EVIDENCE["known_unmet"] = {"studio.txt": ["cobble", "click 8.3.0"]}
    assert stack._closure_record() == {"studio.txt": ["click 8.3.0"]}


def test_a_file_that_includes_another_one_is_never_skipped(monkeypatch, gated, tmp_path) -> None:
    """pass_inputs digests this file; an -r line's target is a second file it does not name,
    and missing_requirements skips flag lines, so a pin behind the include could move with
    nothing in the gate able to see it."""
    _payload, req_root = gated
    outer = req_root / "studio.txt"
    outer.write_text("-r nested.txt\n", encoding = "utf-8")
    (req_root / "nested.txt").write_text("cobble==0.1.3\n", encoding = "utf-8")
    monkeypatch.setattr(stack, "_inputs_unchanged", lambda keys: True)
    monkeypatch.setattr(stack, "_effective_requirements", lambda r: (r, []))
    assert stack._requirements_satisfied(outer, no_deps = True) is False
    # REQ_ROOT points at the temporary copy here, so read the repo's own tree.
    root = REPO_ROOT / "studio" / "backend" / "requirements"
    shipped = [
        name
        for name in stack.install_manifest.PASS_INPUT_FILES
        if (root / name).is_file() and stack._includes_another_requirements_file(root / name)
    ]
    assert shipped == []


def test_an_unreadable_requirements_file_is_never_skipped(tmp_path) -> None:
    """A file the gate cannot read is one whose contents it cannot stand behind."""
    odd = tmp_path / "req.txt"
    odd.write_bytes(b"\xff\xfe not utf-8\n")
    assert stack._includes_another_requirements_file(odd) is True
    assert stack._includes_another_requirements_file(tmp_path / "absent.txt") is True


def test_a_carried_known_unmet_record_drops_what_is_met_again(monkeypatch, gated) -> None:
    """A skipped step carries its record narrowed to what the closure still lacks, since keeping an
    entry satisfied since recording would let a later loss pass as intentional."""
    _payload, req_root = gated
    monkeypatch.setattr(stack, "_AUDITED_STEPS", {"studio.txt": req_root / "studio.txt"})
    monkeypatch.setattr(stack, "_STEP_RESULTS", {"studio.txt": "skipped"})
    stack._PASS_EVIDENCE["known_unmet"] = {"studio.txt": ["click 8.3.0", "mammoth"]}
    monkeypatch.setattr(
        stack.install_manifest, "closure_unmet_requirements", lambda *a, **k: ["click 8.3.0"]
    )
    assert stack._closure_record() == {"studio.txt": ["click 8.3.0"]}
    monkeypatch.setattr(stack.install_manifest, "closure_unmet_requirements", lambda *a, **k: [])
    assert stack._closure_record() == {}
    monkeypatch.setattr(
        stack.install_manifest, "closure_unmet_requirements", lambda *a, **k: ["numpy 1.0"]
    )
    assert stack._closure_record() == {}


def test_the_closure_walk_follows_extras_and_survives_cycles(tmp_path) -> None:
    req = tmp_path / "studio.txt"
    req.write_text("alpha[fancy]\n", encoding = "utf-8")
    index = _closure_index(
        alpha = ("1.0", ['beta ; extra == "fancy"', 'zeta ; extra == "other"', "gamma"]),
        beta = ("2.0", []),
        gamma = ("3.0", ["alpha"]),
    )
    assert stack.install_manifest.unsatisfied_closure_requirement(req, index) is None
    without_beta = dict(index)
    without_beta.pop("beta")
    assert stack.install_manifest.unsatisfied_closure_requirement(req, without_beta) == "beta"


def test_an_extra_named_before_pep_685_is_still_followed(tmp_path) -> None:
    """A wheel built before PEP 685 still says extra == "all_files" in its marker, and matching only
    the canonical spelling would silently drop that extra's subtree."""
    req = tmp_path / "studio.txt"
    req.write_text("alpha[all_files]\n", encoding = "utf-8")
    index = _closure_index(alpha = ("1.0", ['beta ; extra == "all_files"']))
    assert stack.install_manifest.unsatisfied_closure_requirement(req, index) == "beta"
    both = dict(index, beta = ("2.0", []))
    assert stack.install_manifest.unsatisfied_closure_requirement(req, both) is None


def test_an_inapplicable_marker_is_not_a_missing_dependency(tmp_path) -> None:
    req = tmp_path / "studio.txt"
    req.write_text("alpha\n", encoding = "utf-8")
    index = _closure_index(alpha = ("1.0", ['pywin32 ; sys_platform == "never-a-platform"']))
    assert stack.install_manifest.unsatisfied_closure_requirement(req, index) is None


@pytest.mark.parametrize(
    "line,reason",
    [
        ("-r other.txt", "<flag line: -r other.txt>"),
        ("--index-url https://example.invalid", "<flag line: --index-url https://example.invalid>"),
    ],
)
def test_the_closure_audit_fails_closed(tmp_path, line, reason) -> None:
    """Every answer that is not a proven-complete closure must install, since a flag line can hide
    requirements from the walk and guessing would skip on ungathered evidence."""
    req = tmp_path / "studio.txt"
    req.write_text(f"{line}\n", encoding = "utf-8")
    assert stack.install_manifest.unsatisfied_closure_requirement(req, {}) == reason


def test_a_direct_url_requirement_fails_closed(tmp_path) -> None:
    """A version says nothing about which ref landed, and the one step that has such a
    requirement is --no-deps and never reaches this audit."""
    req = tmp_path / "studio.txt"
    req.write_text("alpha @ https://example.invalid/alpha.whl\n", encoding = "utf-8")
    index = _closure_index(alpha = ("1.0", []))
    got = stack.install_manifest.unsatisfied_closure_requirement(req, index)
    assert got == "alpha (direct reference)"


def test_an_unreadable_requirements_file_fails_closed(tmp_path) -> None:
    assert (
        stack.install_manifest.unsatisfied_closure_requirement(tmp_path / "gone.txt", {})
        == "<requirements unreadable>"
    )


def test_a_budget_overrun_fails_closed(monkeypatch, tmp_path) -> None:
    """A site-packages on a wedged mount must cost one dependency pass, not a hang."""
    req = tmp_path / "studio.txt"
    req.write_text("alpha\n", encoding = "utf-8")
    index = _closure_index(alpha = ("1.0", []))
    clock = iter([0.0, 100.0, 200.0])
    monkeypatch.setattr(stack.install_manifest.time, "monotonic", lambda: next(clock))
    assert (
        stack.install_manifest.unsatisfied_closure_requirement(req, index, budget_seconds = 1.0)
        == "<closure audit timed out>"
    )


def test_a_broken_closure_runs_a_with_deps_step_but_not_a_no_deps_one(monkeypatch, gated) -> None:
    """--no-deps steps leave their requirements' own dependencies unresolved on purpose,
    so auditing one would report a conflict the installer created and force it forever."""
    _payload, req_root = gated
    monkeypatch.setattr(
        stack.install_manifest,
        "closure_unmet_requirements",
        lambda *a, **k: ["botocore"],
    )
    assert stack._requirements_satisfied(req_root / "studio.txt", no_deps = False) is False
    assert stack._requirements_satisfied(req_root / "studio.txt", no_deps = True) is True


def test_the_closure_audit_reads_the_filtered_file(monkeypatch, gated) -> None:
    """The temp copy _effective_requirements builds is unlinked on the way out, so an
    audit placed after that cleanup would read nothing and never skip again."""
    _payload, req_root = gated
    monkeypatch.setattr(stack, "PLATFORM_LACKS_TORCHCODEC_WHEEL", True)
    seen: list[bool] = []

    def audit(path, *_a, **_k):
        seen.append(pathlib.Path(path).is_file())
        return []

    monkeypatch.setattr(stack.install_manifest, "closure_unmet_requirements", audit)
    assert stack._requirements_satisfied(req_root / "studio.txt", no_deps = False) is True
    assert seen == [True]


def test_every_gated_step_states_whether_it_installs_with_deps() -> None:
    """no_deps is keyword-only and required so a new step cannot inherit the weaker
    check by forgetting to answer. Pinned on the source, since the failure is silent."""
    source = STACK_PATH.read_text(encoding = "utf-8")
    tree = ast.parse(source)
    for node in ast.walk(tree):
        if not isinstance(node, ast.FunctionDef) or node.name not in (
            "_skip_step",
            "_requirements_satisfied",
        ):
            continue
        names = [arg.arg for arg in node.args.kwonlyargs]
        assert "no_deps" in names, node.name
        defaults = dict(zip(names, node.args.kw_defaults))
        assert defaults["no_deps"] is None, f"{node.name}: no_deps must have no default"


@pytest.mark.parametrize("value", ["1", "true", "YES", " on "])
def test_the_escape_hatch_reaches_the_pin_shaped_steps(monkeypatch, value) -> None:
    """torchao, MLX and torchcodec compare against the installed distribution rather than a recorded
    digest, so a satisfied pin read as nothing to do even on a full pass."""
    monkeypatch.setattr(stack, "_PASS_EVIDENCE", {"pass_inputs": {}, "step_results": {}})
    assert stack._may_skip_on_evidence() is True
    monkeypatch.setenv(stack._FULL_DEPS_ENV, value)
    assert stack._may_skip_on_evidence() is False


def test_a_rejected_manifest_reaches_the_pin_shaped_steps(monkeypatch) -> None:
    monkeypatch.delenv(stack._FULL_DEPS_ENV, raising = False)
    monkeypatch.setattr(stack, "_PASS_EVIDENCE", None)
    assert stack._may_skip_on_evidence() is False


def test_a_satisfied_torchao_pin_is_still_reinstalled_on_a_forced_pass(monkeypatch) -> None:
    calls: list[tuple] = []
    monkeypatch.setattr(stack, "_select_torchao_spec", lambda _v: "torchao==0.18.0")
    monkeypatch.setattr(stack, "_torch_accelerator_index_url", lambda _v: "")
    monkeypatch.setattr(stack, "_pin_needs_reinstall", lambda *_a: False)
    monkeypatch.setattr(stack, "_note", lambda *_a, **_k: None)
    monkeypatch.setattr(stack, "pip_install", lambda *a, **k: calls.append(a))

    monkeypatch.setattr(stack, "_PASS_EVIDENCE", {"pass_inputs": {}, "step_results": {}})
    monkeypatch.delenv(stack._FULL_DEPS_ENV, raising = False)
    stack._install_torchao_for_torch("2.10.0")
    assert calls == []
    assert stack._STEP_RESULTS.get("torchao") == "skipped"

    monkeypatch.setattr(stack, "_PASS_EVIDENCE", None)
    stack._install_torchao_for_torch("2.10.0")
    assert len(calls) == 1
    assert stack._STEP_RESULTS.get("torchao") == "ran"
    assert "--force-reinstall" not in calls[0]

    monkeypatch.setattr(stack, "_pin_needs_reinstall", lambda *_a: True)
    stack._install_torchao_for_torch("2.10.0")
    assert "--force-reinstall" in calls[1]


def test_the_mlx_and_codec_skips_ask_for_the_evidence_too() -> None:
    """Both skips live inside install_python_stack's body, so the guard is pinned on the
    source: a satisfied pin must not outrank a forced or repair pass."""
    source = STACK_PATH.read_text(encoding = "utf-8")
    mlx_guard = (
        "                _may_skip_on_evidence()\n"
        "                and _mlx_stack_is_current()\n"
        '                and _inputs_unchanged(["single-env/overrides-darwin-arm64.txt"])\n'
    )
    assert mlx_guard in source
    assert "_may_skip_on_evidence()\n            and not _codec_rebuild\n" in source


def test_the_npp_repair_is_not_conditional_on_reinstalling_the_codec() -> None:
    """NPP is a separate distribution, so its repair must not depend on the codec step: a skipped
    codec would hide a missing NPP that torchcodec's CUDA build needs."""
    source = STACK_PATH.read_text(encoding = "utf-8")
    assert "        elif _codec_index:\n" in source
    assert source.count('_STEP_RESULTS.get("torchcodec") == "ran"') == 1
    assert '_npp_name = re.split(r"[<>=!~]", _npp_spec, maxsplit = 1)[0].strip()' in source
    assert "if _npp_have and _spec_is_satisfied(_npp_spec, _npp_have):" in source


def test_a_damaged_plugin_payload_is_reinstalled(monkeypatch, tmp_path) -> None:
    """A seed plugin is installed from a path, so its version never moves: deleting the
    installed module leaves both the version and the source digest unchanged."""
    monkeypatch.setattr(
        stack.install_manifest, "damaged_payload_files", lambda *a, **k: ["plugin.py"]
    )
    assert stack._local_plugin_payload_is_damaged("data-designer-github-repo-seed") is True
    monkeypatch.setattr(stack.install_manifest, "damaged_payload_files", lambda *a, **k: [])
    assert stack._local_plugin_payload_is_damaged("data-designer-github-repo-seed") is False


def test_an_unscannable_plugin_is_reinstalled(monkeypatch) -> None:
    """Unlike install_manifest's own convention: this decides whether to skip a local
    path install that costs well under a second, so the conservative answer is cheap."""

    def boom(*_a, **_k):
        raise OSError("no")

    monkeypatch.setattr(stack.install_manifest, "damaged_payload_files", boom)
    assert stack._local_plugin_payload_is_damaged("anything") is True


def test_the_plugin_skip_consults_the_installed_payload() -> None:
    source = STACK_PATH.read_text(encoding = "utf-8")
    assert "and not _local_plugin_payload_is_damaged(plugin_dir.name)" in source


def test_an_unreadable_requires_dist_makes_the_whole_index_unreadable(monkeypatch) -> None:
    """A distribution whose Requires-Dist cannot be read is not a leaf; calling it one
    would let a step skip over a closure the audit never walked."""
    import importlib.metadata

    class _Dist:
        metadata = {"Name": "broken"}
        version = "1.0"

        @property
        def requires(self):
            raise ValueError("unreadable METADATA")

    monkeypatch.setattr(stack.install_manifest, "_metadata_scan_paths", lambda: [])
    monkeypatch.setattr(importlib.metadata, "distributions", lambda **kw: [_Dist()])
    assert stack.install_manifest.installed_dependency_index() is None


def test_pip_backup_metadata_is_not_read_as_installed(tmp_path, monkeypatch) -> None:
    """An interrupted pip upgrade leaves ~ame-1.0.dist-info with the payload gone. pip
    ignores it, so the closure must too, or the step that would reinstall it skips."""
    site = tmp_path / "site-packages"
    backup = site / "~obble-0.1.dist-info"
    backup.mkdir(parents = True)
    (backup / "METADATA").write_text(
        "Metadata-Version: 2.1\nName: cobble\nVersion: 0.1\n", encoding = "utf-8"
    )
    live = site / "mammoth-1.0.dist-info"
    live.mkdir()
    (live / "METADATA").write_text(
        "Metadata-Version: 2.1\nName: mammoth\nVersion: 1.0\n", encoding = "utf-8"
    )
    monkeypatch.setattr(stack.install_manifest, "_metadata_scan_paths", lambda: [str(site)])
    index = stack.install_manifest.installed_dependency_index()
    assert index is not None
    assert "mammoth" in index
    assert "cobble" not in index, "the backup metadata was read as an installed package"


def test_a_second_pass_in_one_process_starts_with_no_audited_steps() -> None:
    """The reset block clears what the previous pass registered, so a step this pass
    never reaches is not audited and recorded as known-unmet on its behalf."""
    source = (stack.__file__ and open(stack.__file__, encoding = "utf-8").read()) or ""
    reset = source.index("_STEP_RESULTS.clear()")
    assert "_AUDITED_STEPS.clear()" in source[reset : reset + 400]


def test_the_mlx_payload_check_walks_each_records_files(monkeypatch, tmp_path) -> None:
    """find_spec sees only the top-level directory; a module the RECORD names that is
    gone or truncated is what makes the recorded verdict false, so it is what is checked."""
    import importlib.metadata
    import importlib.util
    from types import SimpleNamespace

    payload = tmp_path / "mlx_lm" / "sample_utils.py"
    payload.parent.mkdir()
    payload.write_bytes(b"x" * 10)

    # RECORD rows, not Distribution.files: CPython 3.13 drops missing paths from `files`.
    record = {"text": "mlx_lm/sample_utils.py,sha256=x,10\nmlx_lm/__pycache__/x.pyc,,\n"}
    dist = SimpleNamespace(
        read_text = lambda name: record["text"] if name == "RECORD" else None,
        locate_file = lambda f: tmp_path / str(f),
    )
    asked: list[str] = []

    def distribution(name):
        asked.append(name)
        return dist

    monkeypatch.setattr(importlib.util, "find_spec", lambda name: object())
    monkeypatch.setattr(importlib.metadata, "distribution", distribution)
    monkeypatch.setattr(
        stack,
        "_installed_distribution_version",
        lambda name: None if name == "sentencepiece" else "1.0",
    )
    assert stack._mlx_payload_present() is True
    assert set(asked) >= {"mlx", "mlx-metal", "mlx-lm", "mlx-vlm"}
    assert set(asked) >= set(stack._MLX_IMPORTED_DEPENDENCIES) - {"sentencepiece"}
    assert "sentencepiece" not in asked
    payload.write_bytes(b"x" * 3)
    assert stack._mlx_payload_present() is False
    payload.write_bytes(b"x" * 10)
    assert stack._mlx_payload_present() is True
    payload.unlink()
    assert stack._mlx_payload_present() is False
    payload.write_bytes(b"x" * 10)
    record["text"] = None
    assert stack._mlx_payload_present() is False


def test_the_parked_manifest_goes_right_after_the_live_one_is_removed(monkeypatch, tmp_path):
    """remove_manifest parks the live copy for setup.ps1's ordering; a parked copy that outlived a
    killed pass would later be read as evidence of a completed pass."""
    manifest = stack.install_manifest
    live = tmp_path / manifest.MANIFEST_NAME
    parked = tmp_path / manifest.PREVIOUS_MANIFEST_NAME
    live.write_text("{}", encoding = "utf-8")
    monkeypatch.setattr(manifest, "manifest_path", lambda root = None: live)
    monkeypatch.setattr(manifest, "previous_manifest_path", lambda root = None: parked)
    assert manifest.remove_manifest() is True
    assert not live.exists() and parked.exists()
    manifest.consume_previous_manifest()
    assert not parked.exists()
    source = open(stack.__file__, encoding = "utf-8").read()
    at = source.index("if install_manifest.remove_manifest():")
    assert "install_manifest.consume_previous_manifest()" in source[at : at + 200]
    assert "manifest_is_present(_parked)" in source[at : at + 400]


def test_an_input_missing_from_the_record_or_unreadable_now_is_changed(monkeypatch, tmp_path):
    """Pass input digests must not be compared with .get: a file missing from the record and one
    unreadable now both yield None and would wrongly read as unchanged."""
    monkeypatch.setattr(stack, "REQ_ROOT", tmp_path)
    monkeypatch.setattr(stack, "_PASS_EVIDENCE", {"pass_inputs": {"studio.txt": "abc"}})
    digests = {"studio.txt": "abc"}
    monkeypatch.setattr(stack.install_manifest, "digest_file", lambda p: digests.get(p.name))
    assert stack._inputs_unchanged(["studio.txt"]) is True
    assert stack._inputs_unchanged(["extras.txt"]) is False, "not recorded, not readable: unchanged"
    digests["studio.txt"] = None
    assert stack._inputs_unchanged(["studio.txt"]) is False, "recorded, unreadable now"
    digests["studio.txt"] = "def"
    assert stack._inputs_unchanged(["studio.txt"]) is False


def test_the_parked_manifest_is_consumed_when_it_is_read_as_evidence(monkeypatch, tmp_path):
    """The live manifest is removed before a pass so a killed pass leaves nothing that
    verifies as complete; the parked copy follows the same rule once read."""
    parked = tmp_path / "unsloth_install_manifest.previous.json"
    parked.write_text("{}", encoding = "utf-8")
    monkeypatch.setattr(stack.install_manifest, "previous_manifest_path", lambda root = None: parked)
    stack.install_manifest.consume_previous_manifest()
    assert not parked.exists()
    stack.install_manifest.consume_previous_manifest()
    source = open(stack.__file__, encoding = "utf-8").read()
    at = source.index("manifest = install_manifest.read_previous_manifest()")
    assert "install_manifest.consume_previous_manifest()" in source[at : at + 700]
    planner = source[source.index("def _plan_pass(") :]
    assert planner.index("consume_previous_manifest()") < planner.index("_full_deps_requested()")
    assert planner.index("consume_previous_manifest()") < planner.index(
        "_foreign_resolver_inputs()"
    )


def test_duplicate_constrained_metadata_is_a_violation_not_an_absence(monkeypatch, tmp_path):
    """Two pyarrow records: importlib.metadata answers from whichever it meets first, so
    the pinned one can hide the other; the step that puts one record back must run."""
    manifest = stack.install_manifest
    req = tmp_path / "constraints.txt"
    req.write_text("pyarrow==15.0.0\nnumpy>=1.0\n", encoding = "utf-8")
    versions = {"pyarrow": ["15.0.0", "16.0.0"], "numpy": ["2.0.0"]}
    monkeypatch.setattr(manifest, "installed_versions", lambda name: versions.get(name, []))
    assert manifest.violated_constraints(req_file = req) == ["pyarrow"]
    versions["pyarrow"] = ["15.0.0"]
    assert manifest.violated_constraints(req_file = req) == []
    versions["pyarrow"] = [""]
    assert manifest.violated_constraints(req_file = req) == ["pyarrow"]


@pytest.fixture
def audited(monkeypatch, tmp_path):
    """By the time the record is written, the requirements file may be gone or not UTF-8."""
    req_root = tmp_path / "requirements"
    (req_root / "single-env").mkdir(parents = True)
    for name in stack.install_manifest.PASS_INPUT_FILES:
        (req_root / name).write_text(f"# {name}\n", encoding = "utf-8")
    monkeypatch.setattr(stack, "REQ_ROOT", req_root)
    monkeypatch.setattr(stack, "CONSTRAINTS", req_root / "single-env" / "constraints.txt")
    monkeypatch.setattr(stack, "IS_WINDOWS", True)
    monkeypatch.setattr(stack, "NO_TORCH", False)
    monkeypatch.setattr(stack, "IS_MAC_ARM", False)
    monkeypatch.setattr(stack, "PLATFORM_LACKS_TORCHCODEC_WHEEL", False)
    monkeypatch.setattr(stack.install_manifest, "missing_requirements", lambda *a, **k: [])
    monkeypatch.setattr(stack.install_manifest, "violated_constraints", lambda *a, **k: [])
    monkeypatch.setattr(stack.install_manifest, "closure_unmet_requirements", lambda *a, **k: [])
    monkeypatch.setattr(stack.install_manifest, "installed_dependency_index", lambda *a, **k: {})
    stack._AUDITED_STEPS["studio.txt"] = req_root / "studio.txt"
    return req_root


def test_a_requirements_file_the_update_replaced_still_lets_the_manifest_be_written(
    audited,
) -> None:
    """A requirements file the update replaced must not stop the manifest being written: otherwise
    every package installs, the pass dies, and the missing manifest looks half-built."""
    (audited / "studio.txt").unlink()
    assert isinstance(stack._closure_record(), dict)


def test_a_requirements_file_that_is_not_utf8_still_lets_the_manifest_be_written(audited) -> None:
    (audited / "studio.txt").write_bytes(b"\xff\xfe studio\n")
    assert isinstance(stack._closure_record(), dict)


def test_a_temp_copy_that_cannot_be_written_still_lets_the_manifest_be_written(
    audited, monkeypatch
) -> None:
    """_filter_requirements already falls back from the requirements tree to the system
    temp dir; a host that refuses both is a reason to record nothing, not to fail."""

    def _refuse(*a, **k):
        raise OSError("read-only file system")

    monkeypatch.setattr(stack.tempfile, "NamedTemporaryFile", _refuse)
    assert isinstance(stack._closure_record(), dict)


def test_a_step_whose_file_moved_mid_pass_runs_rather_than_raising(audited) -> None:
    """The same read, one line earlier, inside the gate."""
    target = audited / "studio.txt"
    stack._PASS_EVIDENCE = {
        "pass_inputs": {"studio.txt": stack.install_manifest.digest_file(target)},
        "step_results": {"studio.txt": "ran"},
    }
    target.unlink()
    assert stack._requirements_satisfied(target, no_deps = False) is False


def test_a_triton_requirements_file_that_is_not_utf8_does_not_end_the_step(tmp_path) -> None:
    """triton-kernels.txt is read for its git direct reference. utf-8-sig raises a
    UnicodeDecodeError, not an OSError, and this step could not fail before."""
    target = tmp_path / "triton-kernels.txt"
    target.write_bytes(b"\xff\xfe git+https://example.invalid/x@abcdef1\n")
    assert stack._direct_reference_in_requirements(target) is None


def test_every_uninstall_is_counted() -> None:
    """Every uninstall must bump the counter, or the constraint and closure caches go stale."""
    tree = ast.parse(STACK_PATH.read_text(encoding = "utf-8"))
    offenders = []
    for node in ast.walk(tree):
        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
            continue
        body = ast.dump(node)
        if "'uninstall'" not in body and '"uninstall"' not in body:
            continue
        if "_count_install_action" not in body:
            offenders.append(node.name)
    assert not offenders, f"uninstalls that do not move the counter: {offenders}"


def test_rejecting_a_flash_attn_wheel_counts_as_an_install_action(monkeypatch) -> None:
    monkeypatch.setattr(stack, "_INSTALL_ACTIONS", 0)
    monkeypatch.setattr(stack, "USE_UV", False)
    monkeypatch.setattr(
        stack.subprocess, "run", lambda *a, **k: types.SimpleNamespace(returncode = 0)
    )
    assert stack._remove_rejected_flash_attn() is True
    assert stack._INSTALL_ACTIONS == 1


def test_installing_a_flash_attn_wheel_counts_as_an_install_action(monkeypatch) -> None:
    """install_wheel lands a distribution without going through pip_install, so nothing
    else on that path moves the counter."""
    monkeypatch.setattr(stack, "_INSTALL_ACTIONS", 0)
    monkeypatch.setattr(stack, "NO_TORCH", False)
    monkeypatch.setattr(stack, "IS_WINDOWS", False)
    monkeypatch.setattr(stack, "IS_MACOS", False)
    monkeypatch.setattr(stack, "_flash_attn_install_disabled", lambda: False)
    monkeypatch.setattr(stack, "_flash_attn_importable", lambda: False)
    monkeypatch.setattr(stack, "probe_torch_wheel_env", lambda **_k: {"torch": "2.8.0"})
    monkeypatch.setattr(stack, "_build_flash_attn_wheel_url", lambda env: "https://x.invalid/w")
    monkeypatch.setattr(stack, "url_exists", lambda url, **k: True)
    monkeypatch.setattr(
        stack,
        "install_wheel",
        lambda *a, **k: iter([("uv", types.SimpleNamespace(returncode = 1, stdout = "", stderr = ""))]),
    )
    monkeypatch.setattr(stack, "_print_optional_install_failure", lambda *a, **k: None)
    monkeypatch.setattr(stack, "_step", lambda *a, **k: None)
    stack._ensure_flash_attn()
    assert stack._INSTALL_ACTIONS == 1


def test_the_installed_index_is_rebuilt_against_a_fresh_metadata_listing(monkeypatch) -> None:
    """Metadata listings are memoised by coarse mtime; rebuild the index only after invalidate_caches()."""
    calls = []
    monkeypatch.setattr(stack, "_CLOSURE_INDEX_CACHE", None)
    monkeypatch.setattr(stack, "_INSTALL_ACTIONS", 0)
    monkeypatch.setattr(stack.importlib, "invalidate_caches", lambda: calls.append(1))
    monkeypatch.setattr(
        stack.install_manifest, "installed_dependency_index", lambda: {"a": ("1", [])}
    )
    assert stack._installed_index() == {"a": ("1", [])}
    assert calls == [1]
    stack._installed_index()
    assert calls == [1]
    stack._count_install_action()
    stack._installed_index()
    assert calls == [1, 1]


def test_an_unclearable_parked_copy_refuses_before_the_live_manifest_is_dropped(
    monkeypatch, tmp_path
) -> None:
    """A parked previous manifest that cannot be cleared must refuse before the live one is dropped."""
    live = tmp_path / stack.install_manifest.MANIFEST_NAME
    live.write_text("{}", encoding = "utf-8")
    parked = tmp_path / stack.install_manifest.PREVIOUS_MANIFEST_NAME
    parked.mkdir()  # cannot be unlinked, and os.replace onto it raises

    monkeypatch.setattr(stack.install_manifest, "venv_root", lambda *a, **k: tmp_path)
    monkeypatch.setattr(stack.install_manifest, "manifest_path", lambda *a, **k: live)
    monkeypatch.setattr(stack.install_manifest, "previous_manifest_path", lambda *a, **k: parked)
    monkeypatch.setattr(stack, "_plan_pass", lambda *a, **k: None)
    monkeypatch.setattr(stack, "_safe_print", lambda *a, **k: None)
    monkeypatch.setattr(stack, "_step", lambda *a, **k: None)
    monkeypatch.setattr(stack, "_progress", lambda *a, **k: None)

    assert stack.install_python_stack() == 1
    assert live.exists(), "the live manifest was dropped before the refusal"
    assert stack.install_manifest.read_manifest(tmp_path) is not None


def test_a_temp_copy_that_cannot_be_unlinked_does_not_end_the_pass(audited, monkeypatch) -> None:
    """A temp copy locked on Windows must not abort the pass after installs, before the manifest write."""
    real = stack.Path.unlink

    def _locked(self, *a, **k):
        if "-filtered-" in self.name:
            raise PermissionError(32, "The process cannot access the file")
        return real(self, *a, **k)

    monkeypatch.setattr(stack.Path, "unlink", _locked)
    assert isinstance(stack._closure_record(), dict)
    stack._PASS_EVIDENCE = {"pass_inputs": {}, "step_results": {}}
    assert stack._requirements_satisfied(audited / "studio.txt", no_deps = False) is False


def test_the_mlx_grammar_engine_is_pinned_skippable_and_never_fatal() -> None:
    """An unpinned --upgrade re-ran on every update, and its SystemExit aborted the install."""
    assert re.fullmatch(r"llguidance==\d+\.\d+\.\d+", stack._LLGUIDANCE_PIN)
    source = STACK_PATH.read_text(encoding = "utf-8")
    step = source[source.index("# 11d.") : source.index("# 12. Patch metadata")]
    assert "_exact_distribution_spec_is_installed(_LLGUIDANCE_PIN)" in step
    assert "not _full_deps_requested() and" in step
    assert "except SystemExit:" in step
    assert "--upgrade" not in step