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.

55.3 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

"""Unit tests for the llama-server pass-through args validator, pinning denylist behaviour."""

from __future__ import annotations

import importlib.util
import re
from pathlib import Path

import pytest

# Load directly to avoid importing the full backend via core/inference/__init__.py.
_LSA_PATH = Path(__file__).resolve().parent.parent / "core" / "inference" / "llama_server_args.py"
_spec = importlib.util.spec_from_file_location("_lsa_test_only", _LSA_PATH)
_lsa = importlib.util.module_from_spec(_spec)
_spec.loader.exec_module(_lsa)
is_managed_flag = _lsa.is_managed_flag
parse_cache_override = _lsa.parse_cache_override
parse_cache_override_per_axis = _lsa.parse_cache_override_per_axis
parse_ctx_override = _lsa.parse_ctx_override
parse_gpu_layers_override = _lsa.parse_gpu_layers_override
parse_reasoning_budget_message_override = _lsa.parse_reasoning_budget_message_override
parse_reasoning_budget_override = _lsa.parse_reasoning_budget_override
parse_split_mode_override = _lsa.parse_split_mode_override
parse_tensor_split_override = _lsa.parse_tensor_split_override
resolve_cache_type_kv = _lsa.resolve_cache_type_kv
resolve_reasoning_budget = _lsa.resolve_reasoning_budget
resolve_reasoning_budget_message = _lsa.resolve_reasoning_budget_message
resolve_reasoning_budget_message_with_env = _lsa.resolve_reasoning_budget_message_with_env
resolve_reasoning_budget_with_env = _lsa.resolve_reasoning_budget_with_env
resolve_tensor_parallel = _lsa.resolve_tensor_parallel
strip_shadowing_flags = _lsa.strip_shadowing_flags
strip_split_mode_only = _lsa.strip_split_mode_only
strip_context_only = _lsa.strip_context_only
extra_args_disable_mmproj = _lsa.extra_args_disable_mmproj
validate_extra_args = _lsa.validate_extra_args


@pytest.mark.parametrize(
    "args",
    [
        ["--top-k", "20"],
        ["--top-p", "0.9", "--min-p", "0.05"],
        ["--seed", "-1"],  # negative value, not a flag
        ["--temp", "0.0"],
        ["--repeat-penalty", "1.05"],
        ["--mirostat", "2", "--mirostat-lr", "0.1"],
        ["--xtc-probability", "0.05", "--xtc-threshold", "0.1"],
        ["--dry-multiplier", "0.5"],
        ["--cache-type-k", "q8_0"],
        ["--cache-type-v", "q8_0"],
        ["--chat-template-file", "/tmp/tpl.jinja"],
        ["--chat-template-kwargs", '{"reasoning_effort":"high"}'],
        ["--spec-type", "ngram-mod"],
        ["--spec-default"],
        ["--spec-type", "draft-mtp"],
        ["--spec-type", "draft-mtp", "--spec-draft-n-max", "6"],
        [
            "--spec-type",
            "ngram-mod,draft-mtp",
            "--spec-draft-n-max",
            "3",
            "--spec-ngram-mod-n-match",
            "24",
            "--spec-ngram-mod-n-min",
            "48",
            "--spec-ngram-mod-n-max",
            "64",
        ],
        ["--reasoning-format", "deepseek"],
        ["-rea", "auto"],
        ["-c", "131072"],
        ["--ctx-size", "8192"],
        ["--flash-attn", "off"],
        ["-fa", "on"],
        ["--no-context-shift"],
        ["--context-shift"],
        ["--jinja"],
        ["--no-jinja"],
        ["-ngl", "-1"],
        ["--gpu-layers", "32"],
        ["-t", "16"],
        ["--threads", "32"],
        ["-fit", "off"],
        ["--fit", "on"],
        ["--fit-ctx", "8192"],
        ["--mlock"],
        ["--no-mmap", "--mlock"],
    ],
)
def test_pass_through_allowed(args):
    assert validate_extra_args(args) == args


def test_none_returns_empty_list():
    assert validate_extra_args(None) == []


def test_empty_list_returns_empty_list():
    assert validate_extra_args([]) == []


def test_the_attached_value_form_is_refused():
    # llama.cpp does not accept --flag=value (only underscore folding).
    with pytest.raises(ValueError, match = "two separate arguments"):
        validate_extra_args(["--top-k=20"])
    assert validate_extra_args(["--top-k", "20"]) == ["--top-k", "20"]
    assert validate_extra_args(["--ctx_size", "4096"]) == ["--ctx_size", "4096"]
    with pytest.raises(ValueError, match = "managed by Unsloth Studio"):
        validate_extra_args(["--parallel=8"])
    assert validate_extra_args(["--override-kv", "a=int:2"]) == ["--override-kv", "a=int:2"]


def test_managed_long_flag_underscore_alias_is_rejected():
    with pytest.raises(ValueError, match = "slot-save-path"):
        validate_extra_args(["--slot_save_path", "/tmp/slots"])


def test_a_bare_positional_is_rejected():
    # A positional could be read as the model path, which denying -m prevents.
    with pytest.raises(ValueError, match = "bare value"):
        validate_extra_args(["foo"])
    assert validate_extra_args(["--numa", "distribute"]) == ["--numa", "distribute"]


@pytest.mark.parametrize(
    "denied",
    [
        "-np",
        "--parallel",
        "--n-parallel",
        "-m",
        "--model",
        "-mu",
        "--model-url",
        "-dr",
        "--docker-repo",
        "-hf",
        "-hfr",
        "--hf-repo",
        "-hff",
        "--hf-file",
        "-hfv",
        "-hfrv",
        "--hf-repo-v",
        "-hffv",
        "--hf-file-v",
        "-hft",
        "--hf-token",
        "-mmu",
        "--mmproj-url",
        "--host",
        "--port",
        "--path",
        "--api-prefix",
        "--reuse-port",
        "--api-key",
        "--api-key-file",
        "--ssl-key-file",
        "--ssl-cert-file",
        "--webui",
        "--no-webui",
        "--ui",
        "--no-ui",
        "--ui-config",
        "--ui-config-file",
        "--ui-mcp-proxy",
        "--no-ui-mcp-proxy",
        "--models-dir",
        "--models-preset",
        "--models-max",
        "--models-autoload",
        "--no-models-autoload",
        "--embedding",
        "--embeddings",
        "--rerank",
        "--reranking",
        "--pooling",
        "--tools",
        # --agent enables all built-in tools incl. exec_shell_command.
        "-ag",
        "--agent",
        "-no-ag",
        "--no-agent",
        "--tools-runtime",
        "--mcp-servers-config",
        "--mcp-servers-json",
        "--cors-origins",
        "--cors-headers",
        "--cors-methods",
        "--cors-credentials",
        "--no-cors-credentials",
        "--media-path",
        "--log-file",
        "--log-disable",
        "--slot-save-path",
        "-h",
        "--help",
        "--usage",
        "--version",
        "--list-devices",
        "-cl",
        "--cache-list",
        "--completion-bash",
        "--webui-config",
        "--webui-config-file",
        "--webui-mcp-proxy",
        "--no-webui-mcp-proxy",
    ],
)
def test_denylist_rejects_all_aliases(denied):
    with pytest.raises(ValueError, match = denied):
        validate_extra_args([denied, "value"])


@pytest.mark.parametrize(
    "args,offending",
    [
        # Pass-through --parallel would override slots while KV fit uses the resolved value.
        (["--parallel", "8"], "--parallel"),
        (["--parallel=8"], "--parallel"),
        (["--n-parallel", "16"], "--n-parallel"),
        (["--n-parallel=16"], "--n-parallel"),
        (["-np", "32"], "-np"),
        (["-np8"], "-np"),
        (["-np64"], "-np"),
        (["--parallel", "999"], "--parallel"),
        (["-np", "0"], "-np"),
        (["-np999"], "-np"),
        (["-np-1"], "-np"),
        (["-np+1"], "-np"),
    ],
)
def test_parallel_flags_are_managed(args, offending):
    with pytest.raises(ValueError, match = re.escape(offending)):
        validate_extra_args(args)


def test_denylist_rejects_equals_form():
    with pytest.raises(ValueError, match = "--port"):
        validate_extra_args(["--port=9000"])


def test_slot_save_path_is_managed_in_all_forms():
    for args in (["--slot-save-path", "/tmp/x"], ["--slot-save-path=/tmp/x"], ["--slot-save-path"]):
        with pytest.raises(ValueError, match = "--slot-save-path"):
            validate_extra_args(args)
    assert is_managed_flag("--slot-save-path") is True
    assert is_managed_flag("--slot-save-path=/tmp/x") is True
    assert is_managed_flag("--slots") is False
    assert is_managed_flag("--no-slots") is False
    assert is_managed_flag("--props") is False


@pytest.mark.parametrize(
    "padded",
    [" --parallel", "--parallel ", "\t--parallel", "  -np", "-np \n", "-np\t"],
)
def test_denylist_rejects_whitespace_padded_forms(padded):
    with pytest.raises(ValueError, match = "parallel|np"):
        validate_extra_args([padded, "8"])


@pytest.mark.parametrize(
    "attached",
    ["-np8x", "-np-1foo", "-np+1bar", "-np9zzz"],
)
def test_denylist_rejects_np_with_digit_prefix_and_junk(attached):
    # Must classify the same forms the CLI rewriter expands.
    with pytest.raises(ValueError, match = "np"):
        validate_extra_args([attached])


def test_denylist_rejects_short_form_when_long_is_denied():
    with pytest.raises(ValueError, match = "-m"):
        validate_extra_args(["-m", "/some/other/path.gguf"])


def test_denylist_message_names_offending_flag():
    with pytest.raises(ValueError) as excinfo:
        validate_extra_args(["--top-k", "20", "--api-key", "secret"])
    assert "--api-key" in str(excinfo.value)


def test_first_denied_flag_short_circuits():
    with pytest.raises(ValueError, match = "--port"):
        validate_extra_args(["--port", "1", "--host", "x"])


@pytest.mark.parametrize("value", ["-1", "-0.5", "-42", "-.5"])
def test_negative_number_value_is_not_flag(value):
    assert validate_extra_args(["--seed", value]) == ["--seed", value]


def test_is_managed_flag_true_for_denied():
    assert is_managed_flag("--port") is True
    assert is_managed_flag("--api-key") is True
    assert is_managed_flag("-m") is True
    assert is_managed_flag("--model") is True
    assert is_managed_flag("--parallel") is True
    assert is_managed_flag("--n-parallel") is True
    assert is_managed_flag("-np") is True
    # Must stay in sync with validate_extra_args.
    assert is_managed_flag("-np8") is True
    assert is_managed_flag("--parallel=8") is True
    assert is_managed_flag("--port=9000") is True


def test_is_managed_flag_false_for_pass_through():
    assert is_managed_flag("--top-k") is False
    assert is_managed_flag("--cache-type-k") is False
    assert is_managed_flag("--chat-template-file") is False
    assert is_managed_flag("-c") is False
    assert is_managed_flag("--ctx-size") is False
    assert is_managed_flag("--flash-attn") is False
    assert is_managed_flag("-ngl") is False
    assert is_managed_flag("--threads") is False
    assert is_managed_flag("--mlock") is False
    assert is_managed_flag("--no-mmap") is False


def test_strip_shadowing_flags_drops_context_when_requested():
    out = strip_shadowing_flags(
        ["-c", "4096", "--top-k", "20"],
        strip_context = True,
        strip_cache = False,
        strip_spec = False,
        strip_template = False,
    )
    assert out == ["--top-k", "20"]


def test_strip_shadowing_flags_keeps_context_when_not_requested():
    out = strip_shadowing_flags(
        ["-c", "4096", "--top-k", "20"],
        strip_context = False,
        strip_cache = False,
        strip_spec = False,
        strip_template = False,
    )
    assert out == ["-c", "4096", "--top-k", "20"]


def test_strip_shadowing_flags_keeps_chat_template_when_template_disabled():
    out = strip_shadowing_flags(
        ["--chat-template-file", "/tmp/custom.jinja", "--top-k", "20"],
        strip_context = True,
        strip_cache = True,
        strip_spec = True,
        strip_template = False,
    )
    assert out == ["--chat-template-file", "/tmp/custom.jinja", "--top-k", "20"]


def test_strip_shadowing_flags_drops_template_when_requested():
    out = strip_shadowing_flags(
        ["--chat-template-file", "/tmp/custom.jinja", "--top-k", "20"],
        strip_template = True,
    )
    assert out == ["--top-k", "20"]


def test_strip_shadowing_flags_keeps_cache_when_cache_disabled():
    out = strip_shadowing_flags(
        ["--cache-type-k", "q8_0", "--cache-type-v", "q8_0", "--top-k", "20"],
        strip_cache = False,
    )
    assert out == ["--cache-type-k", "q8_0", "--cache-type-v", "q8_0", "--top-k", "20"]


def test_strip_shadowing_flags_keeps_spec_when_spec_disabled():
    out = strip_shadowing_flags(
        ["--spec-type", "ngram-mod", "--draft-min", "48", "--top-k", "20"],
        strip_spec = False,
    )
    assert out == ["--spec-type", "ngram-mod", "--draft-min", "48", "--top-k", "20"]


def test_strip_shadowing_flags_keeps_device_by_default():
    out = strip_shadowing_flags(
        ["--device", "Vulkan1", "--top-k", "20"],
        strip_context = False,
        strip_cache = False,
        strip_spec = False,
        strip_template = False,
        strip_split_mode = False,
    )
    assert out == ["--device", "Vulkan1", "--top-k", "20"]


def test_strip_shadowing_flags_drops_device_when_requested():
    for flag in ("--device", "-dev", "--main-gpu", "-mg"):
        out = strip_shadowing_flags(
            [flag, "Vulkan1", "--top-k", "20"],
            strip_context = False,
            strip_cache = False,
            strip_spec = False,
            strip_template = False,
            strip_split_mode = False,
            strip_device = True,
        )
        assert out == ["--top-k", "20"], flag


def test_strip_shadowing_flags_drops_mtp_flags_when_requested():
    out = strip_shadowing_flags(
        [
            "--spec-type",
            "draft-mtp",
            "--spec-draft-n-max",
            "6",
            "--spec-ngram-mod-n-match",
            "24",
            "--spec-ngram-mod-n-min",
            "48",
            "--spec-ngram-mod-n-max",
            "6",
            "--top-k",
            "20",
        ],
        strip_spec = True,
    )
    assert out == ["--top-k", "20"]


def test_is_managed_flag_false_for_mtp_pass_through():
    assert is_managed_flag("--spec-draft-n-max") is False
    assert is_managed_flag("--spec-ngram-mod-n-match") is False
    assert is_managed_flag("--spec-ngram-mod-n-min") is False
    assert is_managed_flag("--spec-ngram-mod-n-max") is False


@pytest.mark.parametrize(
    "args,expected",
    [
        (None, None),
        ([], None),
        (["--top-k", "20"], None),
        (["--ctx-size", "128000"], 128000),
        (["--ctx-size=128000"], 128000),
        (["-c", "128000"], 128000),
        (["-c=128000"], 128000),
        (["-c", "4096", "--ctx-size", "128000"], 128000),
    ],
)
def test_parse_ctx_override(args, expected):
    assert parse_ctx_override(args) == expected


@pytest.mark.parametrize(
    "args",
    [
        ["--ctx-size"],
        ["--ctx-size", "--top-k"],
        ["--ctx-size", "abc"],
        ["--ctx-size=abc"],
        ["-c", "-1"],
    ],
)
def test_parse_ctx_override_rejects_malformed_values(args):
    with pytest.raises(ValueError, match = "ctx-size|'-c'"):
        parse_ctx_override(args)


def test_validate_extra_args_rejects_malformed_ctx_override():
    with pytest.raises(ValueError, match = "ctx-size"):
        validate_extra_args(["--ctx-size", "abc"])


@pytest.mark.parametrize(
    "args,expected",
    [
        (None, None),
        ([], None),
        (["--top-k", "20"], None),
        (["--gpu-layers", "20"], 20),
        (["--gpu-layers=20"], 20),
        (["--n-gpu-layers", "0"], 0),
        (["-ngl", "-1"], -1),
        (["-ngl", "12", "--gpu-layers", "20"], 20),
    ],
)
def test_parse_gpu_layers_override(args, expected):
    assert parse_gpu_layers_override(args) == expected


@pytest.mark.parametrize("flag", ["-ngl", "--gpu-layers", "--n-gpu-layers"])
@pytest.mark.parametrize("value,expected", [("auto", -1), ("all", 2**31 - 1)])
def test_gpu_layer_keywords_are_preserved_and_resolved(flag, value, expected):
    args = [flag, value]
    assert validate_extra_args(args) == args
    assert parse_gpu_layers_override(args) == expected


@pytest.mark.parametrize(
    "args,expected",
    [
        (["-ngl", "all", "--gpu-layers", "auto"], -1),
        (["-ngl", "auto", "--n-gpu-layers", "all"], 2**31 - 1),
        (["-ngl", "all", "--gpu-layers", "0"], 0),
        (["-ngl", "12", "--gpu-layers", "all"], 2**31 - 1),
    ],
)
def test_gpu_layer_keywords_respect_last_override(args, expected):
    assert validate_extra_args(args) == args
    assert parse_gpu_layers_override(args) == expected


@pytest.mark.parametrize(
    "args",
    [
        ["--gpu-layers"],
        ["--gpu-layers", "--top-k"],
        ["--gpu-layers", "abc"],
        ["--gpu-layers=-2"],
    ],
)
def test_parse_gpu_layers_override_rejects_malformed_values(args):
    with pytest.raises(ValueError, match = "gpu-layers|GPU layers"):
        parse_gpu_layers_override(args)


def test_validate_extra_args_rejects_malformed_gpu_layers_override():
    with pytest.raises(ValueError, match = "GPU layers"):
        validate_extra_args(["-ngl", "abc"])


@pytest.mark.parametrize(
    "args,expected",
    [
        (None, None),
        ([], None),
        (["--top-k", "20"], None),
        (["--tensor-split", "2.2,1"], [2.2, 1.0]),
        (["-ts", "3,1"], [3.0, 1.0]),
        (["-ts", "3/1"], [3.0, 1.0]),
        (["--tensor-split=1,1"], [1.0, 1.0]),
        (["-ts", "1,1", "--tensor-split", "2.2,1"], [2.2, 1.0]),
    ],
)
def test_parse_tensor_split_override(args, expected):
    assert parse_tensor_split_override(args) == expected


@pytest.mark.parametrize(
    "args",
    [
        ["--tensor-split"],
        ["--tensor-split", "--top-k"],
        ["--tensor-split", "abc"],
        ["--tensor-split", "1,-1"],
        ["--tensor-split", "0,0"],
        ["--tensor-split", "nan,1"],
        ["--tensor-split", "inf,1"],
    ],
)
def test_parse_tensor_split_override_rejects_malformed_values(args):
    with pytest.raises(ValueError, match = "tensor-split"):
        parse_tensor_split_override(args)


@pytest.mark.parametrize(
    "value,expected",
    [
        ("1_0,1", [10.0, 1.0]),
        ("1_000.5,1", [1000.5, 1.0]),
        ("1e1_0,1", [1e10, 1.0]),
        ("1.,1", [1.0, 1.0]),
        (".5,1", [0.5, 1.0]),
        ("+1.5,1", [1.5, 1.0]),
    ],
)
def test_parse_tensor_split_override_reads_python_float_syntax(value, expected):
    assert parse_tensor_split_override(["-ts", value]) == expected


@pytest.mark.parametrize("value", ["0x10,1", "0b10,1", "0o17,1", "1__0,1", "_1,1", "1_,1", "1e,1"])
def test_parse_tensor_split_override_rejects_non_float_syntax(value):
    # JS Number() reads 0x/0b/0o, so the mirror must refuse them too.
    with pytest.raises(ValueError, match = "tensor-split"):
        parse_tensor_split_override(["-ts", value])


def test_parse_tensor_split_override_rejects_a_share_float32_cannot_hold():
    # std::stof throws above FLT_MAX, killing llama-server at startup.
    with pytest.raises(ValueError, match = "32-bit float"):
        parse_tensor_split_override(["-ts", "1e39,1"])
    assert parse_tensor_split_override(["-ts", "3.4e38,1"]) == [3.4e38, 1.0]


@pytest.mark.parametrize("value", ["1e-50,1", "1e-45,1", "1e-40,1", "1e-38,1"])
def test_parse_tensor_split_override_rejects_a_share_that_underflows_stof(value):
    # libstdc++ stof also throws on subnormals (1e-38, 1e-45).
    with pytest.raises(ValueError, match = "at least"):
        parse_tensor_split_override(["-ts", value])


@pytest.mark.parametrize("value", ["0,1", "1.2e-38,1", "1e-30,1"])
def test_parse_tensor_split_override_keeps_what_stof_accepts(value):
    # Exact zero and anything from FLT_MIN up survive the emit round trip.
    assert parse_tensor_split_override(["-ts", value]) is not None


def test_parse_tensor_split_override_only_rounds_what_gets_reserialized():
    # Pass-through keeps the user's text, which stof accepts; rounding is manual-only.
    assert parse_tensor_split_override(["-ts", "1.1754943508222874e-38,1"]) is not None
    with pytest.raises(ValueError, match = "at least"):
        parse_tensor_split_override(["-ts", "1.1754943508222874e-38,1"], reserialized = True)


def test_parse_tensor_split_override_rounds_each_share_before_adding():
    # llama.cpp sums float shares, so the total can overflow to inf.
    for reserialized in (False, True):
        with pytest.raises(ValueError, match = "adds up past"):
            parse_tensor_split_override(
                ["-ts", "3.17817e38,1.54601e37,7.00525e36"], reserialized = reserialized
            )


def test_parse_tensor_split_override_judges_the_share_it_will_emit():
    # Manual launcher emits f'{x:g}'; the emitted text must survive stof.
    with pytest.raises(ValueError, match = "at least"):
        parse_tensor_split_override(["-ts", "1.1754943508222874e-38,1"], reserialized = True)
    assert parse_tensor_split_override(["-ts", "1.2e-38,1"], reserialized = True) == [1.2e-38, 1.0]


def test_parse_tensor_split_override_totals_the_emitted_shares():
    # Total is accumulated over the emitted values, as llama.cpp does.
    assert (
        parse_tensor_split_override(
            ["-ts", "2.0829609943909916e38,7.170581961838338e37,6.028042758104631e37"],
            reserialized = True,
        )
        is not None
    )
    with pytest.raises(ValueError, match = "adds up past"):
        parse_tensor_split_override(["-ts", "3e38,3e38"])


def test_parse_tensor_split_override_rejects_a_total_float32_cannot_hold():
    with pytest.raises(ValueError, match = "adds up past"):
        parse_tensor_split_override(["-ts", "3e38,3e38"])


def test_validate_extra_args_rejects_malformed_tensor_split_override():
    with pytest.raises(ValueError, match = "tensor-split"):
        validate_extra_args(["-ts", "abc"])


def test_reasoning_budget_overrides_are_last_wins():
    args = [
        "--reasoning-budget",
        "32",
        "--reasoning-budget=64",
        "--reasoning-budget-message",
        "first",
        "--reasoning-budget-message=limit reached",
    ]
    assert parse_reasoning_budget_override(args) == 64
    assert parse_reasoning_budget_message_override(args) == "limit reached"
    assert resolve_reasoning_budget(args, -1) == 64
    assert resolve_reasoning_budget_message(args, "") == "limit reached"


@pytest.mark.parametrize(
    "args",
    [
        ["--reasoning-budget-message", "  PAD  "],
        ["--reasoning-budget-message=  PAD  "],
    ],
)
def test_reasoning_budget_message_preserves_verbatim_whitespace(args):
    assert parse_reasoning_budget_message_override(args) == "  PAD  "
    assert resolve_reasoning_budget_message(args, "fallback") == "  PAD  "


def test_reasoning_budget_defaults_inherit_env_but_passthrough_still_wins():
    env = {
        "LLAMA_ARG_THINK_BUDGET": "512",
        "LLAMA_ARG_THINK_BUDGET_MESSAGE": "from env",
    }
    assert resolve_reasoning_budget_with_env(None, -1, env) == 512
    assert resolve_reasoning_budget_message_with_env(None, "", env) == "from env"
    assert resolve_reasoning_budget_with_env(["--reasoning-budget", "-1"], -1, env) == -1
    assert (
        resolve_reasoning_budget_message_with_env(
            ["--reasoning-budget-message", "  CLI  "], "", env
        )
        == "  CLI  "
    )


# A NUL trips the list-wide control-character check first.
@pytest.mark.parametrize(
    "unsafe, message",
    [("😀" * 2_049, "reasoning-budget-message"), ("bad\0message", "control characters")],
)
def test_reasoning_budget_message_validates_every_occurrence(unsafe, message):
    with pytest.raises(ValueError, match = message):
        validate_extra_args(
            [
                "--reasoning-budget-message",
                unsafe,
                "--reasoning-budget-message",
                "safe final value",
            ]
        )


@pytest.mark.parametrize(
    "args",
    [
        ["--reasoning-budget"],
        ["--reasoning-budget", "nope"],
        ["--reasoning-budget=-2"],
        ["--reasoning-budget=2147483648"],
        ["--reasoning-budget-message"],
        ["--reasoning-budget-message", "😀" * 2_049],
        ["--reasoning-budget-message", "bad\0message"],
    ],
)
def test_validate_extra_args_rejects_malformed_reasoning_overrides(args):
    with pytest.raises(ValueError, match = "reasoning-budget|control characters"):
        validate_extra_args(args)


def test_strip_reasoning_shadows_is_granular():
    args = [
        "--reasoning-budget",
        "64",
        "--reasoning-budget-message",
        "limit reached",
        "--top-k",
        "20",
    ]
    assert strip_shadowing_flags(
        args,
        strip_context = False,
        strip_cache = False,
        strip_spec = False,
        strip_template = False,
        strip_split_mode = False,
        strip_reasoning_budget = True,
    ) == ["--reasoning-budget-message", "limit reached", "--top-k", "20"]
    assert strip_shadowing_flags(
        args,
        strip_context = False,
        strip_cache = False,
        strip_spec = False,
        strip_template = False,
        strip_split_mode = False,
        strip_reasoning_budget_message = True,
    ) == ["--reasoning-budget", "64", "--top-k", "20"]


@pytest.mark.parametrize(
    "args,expected",
    [
        (None, None),
        ([], None),
        (["--top-k", "20"], None),
        (["--cache-type-k", "q8_0"], "q8_0"),
        (["-ctk", "q4_0"], "q4_0"),
        (["-ctv", "q4_0"], "q4_0"),
        (["--cache-type-k=q4_0"], "q4_0"),
        (["-ctk", "f16", "-ctk", "q8_0"], "q8_0"),
    ],
)
def test_parse_cache_override(args, expected):
    assert parse_cache_override(args) == expected


@pytest.mark.parametrize(
    "args",
    [
        ["-ctk"],
        ["-ctk", "-c", "4096"],
    ],
)
def test_parse_cache_override_rejects_malformed_values(args):
    with pytest.raises(ValueError, match = "cache-type|'-ctk'"):
        parse_cache_override(args)


@pytest.mark.parametrize(
    "args, expected",
    [
        (["--cache-type-k", "f32", "--cache-type-v", "f16"], ("f32", "f16")),
        (["-ctk", "q8_0", "-ctv", "q4_0"], ("q8_0", "q4_0")),
        (["--cache-type-k=f32"], ("f32", None)),
        (["--cache-type-v", "f16"], (None, "f16")),
        (["-c", "4096"], (None, None)),
        (None, (None, None)),
        (["-ctk", "f16", "-ctk", "f32"], ("f32", None)),
    ],
)
def test_parse_cache_override_per_axis(args, expected):
    # Keeps K and V apart, unlike parse_cache_override.
    assert parse_cache_override_per_axis(args) == expected


def test_resolve_cache_type_kv_uses_override_when_present():
    assert resolve_cache_type_kv(["--cache-type-k", "q8_0"], "f16") == "q8_0"


def test_resolve_cache_type_kv_uses_fallback_without_override():
    assert resolve_cache_type_kv(["--top-k", "20"], "f16") == "f16"


def test_strip_shadowing_flags_boolean_does_not_consume_next_token():
    out = strip_shadowing_flags(["--spec-default", "ngram-mod"], strip_spec = True)
    assert out == ["ngram-mod"]


def test_strip_shadowing_flags_jinja_boolean_preserves_positional():
    out = strip_shadowing_flags(["--jinja", "trailing-positional"], strip_template = True)
    assert out == ["trailing-positional"]


def test_strip_shadowing_flags_no_jinja_boolean_preserves_positional():
    out = strip_shadowing_flags(["--no-jinja", "trailing-positional"], strip_template = True)
    assert out == ["trailing-positional"]


def test_strip_shadowing_flags_equals_form_drops_only_the_flag():
    out = strip_shadowing_flags(["--ctx-size=4096", "--seed", "-1"], strip_context = True)
    assert out == ["--seed", "-1"]


def test_strip_shadowing_flags_handles_none_input():
    assert strip_shadowing_flags(None) == []


def test_strip_shadowing_flags_handles_empty_input():
    assert strip_shadowing_flags([]) == []


def test_strip_shadowing_flags_defaults_strip_everything():
    out = strip_shadowing_flags(
        ["-c", "4096", "--cache-type-k", "q8_0", "--spec-default", "--jinja"]
    )
    assert out == []


# --split-mode: soft-shadowed like --cache-type-*, stripped on inherit.


@pytest.mark.parametrize(
    "args",
    [
        ["--split-mode", "tensor"],
        ["--split-mode", "row"],
        ["--split-mode", "none"],
        ["--split-mode", "layer"],
        ["-sm", "tensor"],
    ],
)
def test_split_mode_passes_through(args):
    assert validate_extra_args(args) == args


@pytest.mark.parametrize("args", [["--split-mode=row"], ["-sm=tensor"]])
def test_the_attached_split_mode_spelling_is_refused(args):
    with pytest.raises(ValueError, match = "two separate arguments"):
        validate_extra_args(args)


def test_split_mode_is_not_managed():
    assert is_managed_flag("--split-mode") is False
    assert is_managed_flag("-sm") is False


@pytest.mark.parametrize(
    "args,expected",
    [
        (None, None),
        ([], None),
        (["--top-k", "20"], None),
        (["--split-mode", "tensor"], "tensor"),
        (["--split-mode", "row"], "row"),
        (["-sm", "none"], "none"),
        (["--split-mode=layer"], "layer"),
        (["-sm=tensor"], "tensor"),
        (["-sm", "row", "--split-mode", "tensor"], "tensor"),
    ],
)
def test_parse_split_mode_override(args, expected):
    assert parse_split_mode_override(args) == expected


@pytest.mark.parametrize(
    "args",
    [
        ["--split-mode"],
        ["-sm"],
        ["--split-mode", "-c", "4096"],  # next token is a flag, not a value
    ],
)
def test_parse_split_mode_override_rejects_malformed_values(args):
    with pytest.raises(ValueError, match = "split-mode|'-sm'"):
        parse_split_mode_override(args)


def test_validate_extra_args_rejects_malformed_split_mode():
    with pytest.raises(ValueError, match = "split-mode"):
        validate_extra_args(["--split-mode"])


@pytest.mark.parametrize(
    "args,fallback,expected",
    [
        (["--top-k", "20"], True, True),
        (["--top-k", "20"], False, False),
        (None, True, True),
        ([], False, False),
        (["--split-mode", "tensor"], False, True),
        (["-sm", "tensor"], False, True),
        (["--split-mode", "row"], True, False),
        (["--split-mode", "none"], True, False),
        (["--split-mode", "layer"], True, False),
        (["--split-mode=tensor"], False, True),
        (["--split-mode", "TENSOR"], False, True),
        (["-sm", "tensor", "--split-mode", "row"], True, False),
    ],
)
def test_resolve_tensor_parallel(args, fallback, expected):
    assert resolve_tensor_parallel(args, fallback) is expected


def test_strip_shadowing_flags_drops_split_mode_when_requested():
    out = strip_shadowing_flags(
        ["--split-mode", "row", "--top-k", "20"],
        strip_context = False,
        strip_cache = False,
        strip_spec = False,
        strip_template = False,
        strip_split_mode = True,
    )
    assert out == ["--top-k", "20"]


def test_extra_args_disable_mmproj_detects_flag():
    assert extra_args_disable_mmproj(["--no-mmproj"]) is True
    assert extra_args_disable_mmproj(["--threads", "12", "--no-mmproj"]) is True
    assert extra_args_disable_mmproj(["--no-mmproj-auto"]) is True


def test_extra_args_disable_mmproj_false_when_absent():
    assert extra_args_disable_mmproj(None) is False
    assert extra_args_disable_mmproj(["--threads", "12"]) is False


def test_extra_args_disable_mmproj_last_wins():
    assert extra_args_disable_mmproj(["--no-mmproj", "--mmproj-auto"]) is False
    assert extra_args_disable_mmproj(["--mmproj-auto", "--no-mmproj-auto"]) is True


def test_strip_shadowing_flags_drops_model_draft_with_spec():
    # --model-draft is managed: an inherited copy must not override the drafter.
    out = strip_shadowing_flags(
        ["--model-draft", "/old/mtp.gguf", "-md", "/old2.gguf", "--top-k", "20"],
        strip_context = False,
        strip_cache = False,
        strip_spec = True,
        strip_template = False,
    )
    assert out == ["--top-k", "20"]


@pytest.mark.parametrize(
    "selector",
    [
        ["--spec-draft-hf", "org/repo"],
        ["-hfd", "org/repo"],
        ["-hfrd", "org/repo"],
        ["--hf-repo-draft", "org/repo"],
        ["--spec-draft-hf=org/repo"],
    ],
)
def test_strip_shadowing_flags_drops_hf_drafter_selectors_with_spec(selector):
    out = strip_shadowing_flags(
        selector + ["--top-k", "20"],
        strip_context = False,
        strip_cache = False,
        strip_spec = True,
        strip_template = False,
    )
    assert out == ["--top-k", "20"]


def test_strip_shadowing_flags_keeps_draft_tuning_with_spec():
    # Drafter tuning knobs are kept; stripping --spec-draft-ngl moves a CPU drafter to GPU.
    keep = [
        "--spec-draft-type-k",
        "q4_0",
        "--spec-draft-type-v",
        "q4_0",
        "--spec-draft-ngl",
        "0",
        "--spec-draft-device",
        "cpu",
    ]
    out = strip_shadowing_flags(
        list(keep),
        strip_context = False,
        strip_cache = False,
        strip_spec = True,
        strip_template = False,
    )
    assert out == keep


def test_strip_shadowing_flags_keeps_split_mode_when_not_requested():
    out = strip_shadowing_flags(
        ["--split-mode", "row", "--top-k", "20"],
        strip_context = True,
        strip_cache = True,
        strip_spec = True,
        strip_template = True,
        strip_split_mode = False,
    )
    assert out == ["--split-mode", "row", "--top-k", "20"]


def test_strip_shadowing_flags_drops_split_mode_short_alias_and_equals():
    assert strip_shadowing_flags(["-sm", "tensor", "--top-k", "20"], strip_split_mode = True) == [
        "--top-k",
        "20",
    ]
    assert strip_shadowing_flags(["--split-mode=row", "--seed", "-1"], strip_split_mode = True) == [
        "--seed",
        "-1",
    ]


def test_strip_shadowing_flags_defaults_strip_split_mode_too():
    assert strip_shadowing_flags(["--split-mode", "tensor"]) == []


def test_strip_offload_is_opt_in_and_covers_moe():
    base = dict(
        strip_context = False,
        strip_cache = False,
        strip_spec = False,
        strip_template = False,
        strip_split_mode = False,
    )
    assert strip_shadowing_flags(["--n-cpu-moe", "8", "--top-k", "20"], **base) == [
        "--n-cpu-moe",
        "8",
        "--top-k",
        "20",
    ]
    assert strip_shadowing_flags(
        ["--n-cpu-moe", "8", "--gpu-layers", "33", "--fit", "off", "--top-k", "20"],
        **base,
        strip_offload = True,
    ) == ["--top-k", "20"]
    assert strip_shadowing_flags(["--cpu-moe", "--seed", "-1"], **base, strip_offload = True) == [
        "--seed",
        "-1",
    ]


@pytest.mark.parametrize(
    "args",
    [
        ["--split-mode", "tensor", "-c", "4096"],
        ["-sm", "tensor", "-c", "4096"],
        ["--split-mode=tensor", "-c", "4096"],
        ["-sm=tensor", "-c", "4096"],
    ],
)
def test_strip_split_mode_only_keeps_other_shadow_flags(args):
    assert strip_split_mode_only(args) == ["-c", "4096"]


def test_strip_split_mode_only_preserves_none_and_empty():
    # None means inherit; [] means explicit empty.
    assert strip_split_mode_only(None) is None
    assert strip_split_mode_only([]) == []


@pytest.mark.parametrize(
    "args",
    [
        ["-c", "0", "--top-k", "20"],
        ["--ctx-size", "0", "--top-k", "20"],
        ["-c=0", "--top-k", "20"],
        ["--ctx-size=0", "--top-k", "20"],
    ],
)
def test_strip_context_only_drops_every_context_form(args):
    assert strip_context_only(args) == ["--top-k", "20"]


def test_strip_context_only_keeps_other_shadow_flags():
    assert strip_context_only(["-c", "0", "--split-mode", "row", "--cache-type-k", "q8_0"]) == [
        "--split-mode",
        "row",
        "--cache-type-k",
        "q8_0",
    ]


def test_strip_context_only_preserves_none_and_empty():
    assert strip_context_only(None) is None
    assert strip_context_only([]) == []


def test_strip_shadowing_flags_drops_tensor_split_with_split_mode():
    out = strip_shadowing_flags(
        ["--split-mode", "row", "--tensor-split", "1,1", "--top-k", "20"],
        strip_context = False,
        strip_cache = False,
        strip_spec = False,
        strip_template = False,
        strip_split_mode = True,
    )
    assert out == ["--top-k", "20"]


def test_strip_shadowing_flags_keeps_tensor_split_when_not_requested():
    assert strip_shadowing_flags(
        ["--tensor-split", "1,1", "--top-k", "20"], strip_split_mode = False
    ) == ["--tensor-split", "1,1", "--top-k", "20"]


def test_strip_split_mode_only_drops_tensor_split_too():
    assert strip_split_mode_only(
        ["--split-mode", "tensor", "--tensor-split", "1,1", "-c", "4096"]
    ) == ["-c", "4096"]
    assert strip_split_mode_only(["-sm=tensor", "-ts=3,1"]) == []


def test_strip_tensor_split_alone_preserves_split_mode():
    # strip_tensor_split drops only the ratio; the user's split mode survives.
    out = strip_shadowing_flags(
        ["--split-mode", "row", "--tensor-split", "1,1", "--top-k", "20"],
        strip_context = False,
        strip_cache = False,
        strip_spec = False,
        strip_template = False,
        strip_split_mode = False,
        strip_tensor_split = True,
    )
    assert out == ["--split-mode", "row", "--top-k", "20"]


def test_strip_shadowing_flags_keeps_model_draft_without_spec():
    out = strip_shadowing_flags(
        ["--model-draft", "/custom/mtp.gguf"],
        strip_context = True,
        strip_cache = False,
        strip_spec = False,
        strip_template = False,
    )
    assert out == ["--model-draft", "/custom/mtp.gguf"]


# Not the security boundary (the denylist is), just a size cap before execve.


def test_token_count_is_capped():
    with pytest.raises(ValueError, match = "too many"):
        validate_extra_args(["--verbose"] * (_lsa.MAX_EXTRA_ARG_TOKENS + 1))
    assert len(validate_extra_args(["--verbose"] * _lsa.MAX_EXTRA_ARG_TOKENS)) == (
        _lsa.MAX_EXTRA_ARG_TOKENS
    )


def test_total_size_is_capped():
    with pytest.raises(ValueError, match = "too large"):
        validate_extra_args(["--grammar", "x" * (_lsa.MAX_EXTRA_ARGS_BYTES + 1)])


def test_a_long_single_token_is_allowed_under_the_total():
    # Grammars can be one long token, so the cap is on the list.
    schema = "x" * (_lsa.MAX_EXTRA_ARGS_BYTES // 2)
    assert validate_extra_args(["--grammar", schema]) == ["--grammar", schema]


def test_the_size_cap_counts_bytes_not_characters():
    # Astral chars are 4 bytes; a char-counted cap would undercount.
    big = "\U0001f600" * (_lsa.MAX_EXTRA_ARGS_BYTES // 4)
    with pytest.raises(ValueError, match = "too large"):
        validate_extra_args(["--grammar", big])


@pytest.mark.parametrize("token", ["a\x00b", "a\x07b", "\x1b[31m"])
def test_control_characters_are_rejected(token):
    with pytest.raises(ValueError, match = "control characters"):
        validate_extra_args([token])


@pytest.mark.parametrize("token", ["line\nbreak", "tab\there"])
def test_tab_and_newline_survive(token):
    assert validate_extra_args(["--grammar", token]) == ["--grammar", token]


def test_denied_env_twins_are_scrubbed():
    env = {
        "LLAMA_ARG_AGENT": "1",
        "LLAMA_ARG_TOOLS": "all",
        "LLAMA_ARG_MCP_SERVERS_JSON": "{}",
        "PATH": "/usr/bin",
    }
    removed = _lsa.scrub_denied_env(env)
    assert set(removed) == {"LLAMA_ARG_AGENT", "LLAMA_ARG_TOOLS", "LLAMA_ARG_MCP_SERVERS_JSON"}
    assert env == {"PATH": "/usr/bin"}


def test_scrubbing_is_a_no_op_without_the_twins():
    env = {"PATH": "/usr/bin", "LLAMA_ARG_MLOCK": "1"}
    assert _lsa.scrub_denied_env(env) == []
    assert env == {"PATH": "/usr/bin", "LLAMA_ARG_MLOCK": "1"}


def test_every_denied_env_var_names_a_denied_flag():
    # Both prefixes: llama.cpp uses LLAMA_ and LLAMA_ARG_ depending on flag/release.
    for name in _lsa.DENIED_ENV_VARS:
        stem = name.removeprefix("LLAMA_ARG_").removeprefix("LLAMA_")
        flag = _lsa.DENIED_ENV_TWIN_FLAGS.get(name) or "--" + stem.lower().replace("_", "-")
        assert is_managed_flag(flag), f"{name} has no denied flag ({flag})"


def test_every_denied_flag_with_a_twin_in_the_help_is_scrubbed():
    # Enumerated from b10342 --help; llama.cpp applies env BEFORE argv.
    for env_var, flag in (
        ("LLAMA_ARG_UI_MCP_PROXY", "--ui-mcp-proxy"),
        ("LLAMA_ARG_UI", "--ui"),
        ("LLAMA_ARG_STATIC_PATH", "--path"),
        ("LLAMA_ARG_MODELS_DIR", "--models-dir"),
        ("LLAMA_ARG_MODELS_AUTOLOAD", "--models-autoload"),
        ("LLAMA_ARG_EMBEDDINGS", "--embeddings"),
        ("LLAMA_ARG_RERANKING", "--reranking"),
        ("LLAMA_ARG_MODEL", "--model"),
        ("LLAMA_ARG_HF_REPO", "--hf-repo"),
        ("LLAMA_ARG_HOST", "--host"),
        ("LLAMA_ARG_PORT", "--port"),
        ("LLAMA_ARG_N_PARALLEL", "--parallel"),
        ("LLAMA_ARG_SSL_KEY_FILE", "--ssl-key-file"),
        ("LLAMA_ARG_SSL_CERT_FILE", "--ssl-cert-file"),
    ):
        assert is_managed_flag(flag), flag
        assert env_var in _lsa.DENIED_ENV_VARS, env_var
    env = {name: "1" for name in _lsa.DENIED_ENV_VARS}
    env["PATH"] = "/usr/bin"
    # Projector twins are an input: _launch_has_mmproj reads them for vision/audio state.
    for kept in ("LLAMA_ARG_MMPROJ", "LLAMA_ARG_MMPROJ_URL"):
        assert kept not in _lsa.DENIED_ENV_VARS, kept
    # HF_TOKEN is not scrubbed: Unsloth's own downloads use it.
    assert "HF_TOKEN" not in _lsa.DENIED_ENV_VARS
    _lsa.scrub_denied_env(env)
    assert env == {"PATH": "/usr/bin"}


def test_the_projector_env_twins_survive_the_scrub():
    # Env twin is an input for _launch_has_mmproj; scrubbing made loads text-only.
    env = {
        "LLAMA_ARG_MMPROJ": "/models/mmproj-F16.gguf",
        "LLAMA_ARG_MMPROJ_URL": "https://example.invalid/mmproj-F16.gguf",
        "LLAMA_ARG_AGENT": "1",
    }
    removed = _lsa.scrub_denied_env(env)
    assert removed == ["LLAMA_ARG_AGENT"]
    assert env == {
        "LLAMA_ARG_MMPROJ": "/models/mmproj-F16.gguf",
        "LLAMA_ARG_MMPROJ_URL": "https://example.invalid/mmproj-F16.gguf",
    }
    assert "LLAMA_ARG_MMPROJ" not in _lsa.DENIED_ENV_VARS
    assert "LLAMA_ARG_MMPROJ_URL" not in _lsa.DENIED_ENV_VARS


@pytest.mark.parametrize(
    "env,expected",
    [
        ({}, False),
        (None, False),
        ({"LLAMA_ARG_LOAD_MODE": "mmap"}, True),
        ({"LLAMA_ARG_LOAD_MODE": "dio"}, True),
        ({"LLAMA_ARG_LOAD_MODE": "  "}, False),
        ({"LLAMA_ARG_MLOCK": "1"}, True),
        ({"LLAMA_ARG_MLOCK": "0"}, False),
        ({"LLAMA_ARG_MMAP": "on"}, True),
        ({"LLAMA_ARG_MMAP": "off"}, True),
        ({"LLAMA_ARG_DIO": "1"}, True),
        # Negative aliases count by presence: get_value_from_env forces '0'.
        ({"LLAMA_ARG_NO_MMAP": "0"}, True),
        ({"LLAMA_ARG_NO_DIO": ""}, True),
        ({"LLAMA_ARG_FIT": "off", "LLAMA_ARG_DEVICE": "none"}, False),
    ],
)
def test_memory_env_selects_load_mode(env, expected):
    assert _lsa.memory_env_selects_load_mode(env) is expected


# Both strip paths share this test so a value survives either reload.


def test_matching_ctx_override_confirms_only_an_exact_positive_int():
    assert _lsa.matches_explicit_ctx_override(["--ctx-size", "100352"], 100352)
    assert _lsa.matches_explicit_ctx_override(["-c", "100352"], 100352)
    assert _lsa.matches_explicit_ctx_override(["--ctx_size", "100352"], 100352)
    assert _lsa.matches_explicit_ctx_override(
        ["--ctx-size", "8192", "--ctx-size", "100352"], 100352
    )
    assert not _lsa.matches_explicit_ctx_override(
        ["--ctx-size", "100352", "--ctx-size", "8192"], 100352
    )
    assert not _lsa.matches_explicit_ctx_override(["--ctx-size", "8192"], 100352)
    assert not _lsa.matches_explicit_ctx_override(["--top-k", "40"], 100352)
    assert not _lsa.matches_explicit_ctx_override(None, 100352)


def test_matching_ctx_override_is_total_over_stored_junk():
    # Rows are returned verbatim on read, so any legacy JSON must not raise.
    for n_ctx in (None, 0, -1, "100352", "", "x", 100352.0, True, False, [100352], {"v": 1}):
        assert not _lsa.matches_explicit_ctx_override(["--ctx-size", "100352"], n_ctx), n_ctx
    assert not _lsa.matches_explicit_ctx_override(["--ctx-size", "--top-k"], 100352)


# llama.cpp is last-wins: strip must read the EFFECTIVE mlock/mmap state.


def _rewritten_state(argv, env = None):
    """``((mlock, reserves_ram), argv, env)`` after the pageable rewrite."""
    env = dict(env or {})
    out, overridden = _lsa.force_pageable_load(list(argv), env)
    return _lsa.resolve_effective_memory_state(out, env), out, env, overridden


@pytest.mark.parametrize(
    "argv",
    [
        ["--mlock", "--no-mmap"],
        ["--mlock", "--no-direct-io"],
        ["--mlock", "--load-mode", "none"],
        ["--load-mode", "mlock", "--no-mmap"],
        ["--load-mode=mlock", "--no-mmap"],
        ["--load-mode", "mmap+mlock", "--no-mmap"],
        ["--load-mode=mmap+mlock", "--no-mmap"],
        ["--load-mode", "mmap+mlock", "--no-direct-io"],
    ],
    ids = [
        "no-mmap",
        "no-dio",
        "load-mode-none",
        "load-mode-mlock",
        "load-mode-mlock-equals",
        "load-mode-mmap-mlock",
        "load-mode-mmap-mlock-equals",
        "load-mode-mmap-mlock-no-dio",
    ],
)
def test_a_shadowed_lock_is_not_resurrected_by_the_pageable_rewrite(argv):
    assert _lsa.resolve_effective_memory_state(argv) == (False, True)

    (mlock, reserves), out, _env, overridden = _rewritten_state(argv)

    assert overridden, f"the unmapped launch was not rewritten at all: {out}"
    assert not reserves, f"the child still holds a full unmapped copy: {out}"
    assert not mlock, f"the rewrite page-locked the oversized mapping: {out}"


@pytest.mark.parametrize(
    "argv, expect_tokens",
    [
        (["--no-mmap", "--mlock"], ["--mlock"]),
        (["--load-mode", "mlock"], ["--load-mode", "mmap+mlock"]),
        (["--load-mode=mlock"], ["--load-mode", "mmap+mlock"]),
    ],
    ids = ["no-mmap-then-mlock", "load-mode-mlock", "load-mode-mlock-equals"],
)
def test_an_effective_lock_survives_the_pageable_rewrite(argv, expect_tokens):
    """Control: a keep-in-RAM request is mmap+mlock unless a flag shadows it, not discarded."""
    assert _lsa.resolve_effective_memory_state(argv) == (True, True)

    (mlock, reserves), out, _env, overridden = _rewritten_state(argv)

    assert overridden, f"the unmapped launch was not rewritten at all: {out}"
    assert (mlock, reserves) == (True, False), f"the lock was dropped or kept unmapped: {out}"
    assert out == expect_tokens, out


def test_the_env_twin_of_a_shadowed_lock_goes_too():
    """An env LLAMA_ARG_MLOCK beside LLAMA_ARG_NO_MMAP is shadowed like its argv pair, so strip it too."""
    env = {"LLAMA_ARG_MLOCK": "1", "LLAMA_ARG_NO_MMAP": "1"}
    assert _lsa.resolve_effective_memory_state([], env) == (False, True)

    (mlock, reserves), _out, out_env, overridden = _rewritten_state([], env)

    assert "LLAMA_ARG_NO_MMAP" not in out_env
    assert "LLAMA_ARG_MLOCK" not in out_env, out_env
    assert "LLAMA_ARG_MLOCK" in overridden, overridden
    assert (mlock, reserves) == (False, False)


def test_the_env_mapped_lock_mode_shadowed_by_an_argv_selector_goes_too():
    """An env LLAMA_ARG_LOAD_MODE shadowed by an argv --no-mmap still locks the child; strip it too."""
    env = {"LLAMA_ARG_LOAD_MODE": "mmap+mlock"}
    assert _lsa.resolve_effective_memory_state(["--no-mmap"], env) == (False, True)

    (mlock, reserves), _out, out_env, overridden = _rewritten_state(["--no-mmap"], env)

    assert "LLAMA_ARG_LOAD_MODE" not in out_env, out_env
    assert overridden, "the unmapped launch was not rewritten at all"
    assert (mlock, reserves) == (
        False,
        False,
    ), f"the rewrite page-locked the oversized mapping: {out_env}"


def test_an_unshadowed_mapped_lock_is_left_entirely_alone():
    """An unshadowed mmap+mlock already maps, so it must be left untouched and reported as no override."""
    argv = ["--load-mode", "mmap+mlock"]
    assert _lsa.resolve_effective_memory_state(argv) == (True, False)

    (mlock, reserves), out, _env, overridden = _rewritten_state(argv)

    assert out == argv, out
    assert not overridden, f"an already-mapped launch was reported as overridden: {overridden}"
    assert (mlock, reserves) == (True, False)


def test_the_env_mlock_mode_that_is_not_shadowed_keeps_its_lock():
    """The control for the env half: LLAMA_ARG_LOAD_MODE=mlock with nothing after it
    really is locked, so it becomes the mapped twin instead of being dropped."""
    env = {"LLAMA_ARG_LOAD_MODE": "mlock"}
    assert _lsa.resolve_effective_memory_state([], env) == (True, True)

    (mlock, reserves), _out, out_env, _overridden = _rewritten_state([], env)

    assert out_env["LLAMA_ARG_LOAD_MODE"] == "mmap+mlock"
    assert (mlock, reserves) == (True, False)


def test_an_argv_lock_that_overrides_an_inherited_selector_survives():
    """The cross case, and the reason the rewrite cannot read either side alone: argv
    is resolved after the environment, so --mlock beats an inherited LLAMA_ARG_NO_MMAP
    and the lock is the user's live request."""
    env = {"LLAMA_ARG_NO_MMAP": "1"}
    argv = ["--mlock"]
    assert _lsa.resolve_effective_memory_state(argv, env) == (True, True)

    (mlock, reserves), out, out_env, _overridden = _rewritten_state(argv, env)

    assert "LLAMA_ARG_NO_MMAP" not in out_env
    assert out == ["--mlock"], out
    assert (mlock, reserves) == (True, False)


def test_a_pageable_launch_keeps_every_token_including_its_lock():
    """Nothing here reserves RAM, so the override does not apply and the launch comes
    back byte for byte -- the mlock strip is scoped to a rewrite, not to any --mlock."""
    argv = ["--mlock", "--load-mode", "dio"]
    assert _lsa.resolve_effective_memory_state(argv) == (False, False)

    out, overridden = _lsa.force_pageable_load(list(argv), {})

    assert out == argv and overridden == []


@pytest.mark.parametrize("flag", ["--mmproj", "-mm"])
def test_custom_projector_is_allowed(flag):
    args = [flag, "/models/custom projector.gguf"]
    assert validate_extra_args(args) == args


def test_ngram_mod_extras_are_respelled_for_a_legacy_build():
    from core.inference.llama_server_args import translate_ngram_mod_args

    knobs = [
        "--spec-ngram-mod-n-match",
        "16",
        "--spec-ngram-mod-n-min=8",
        "--spec-ngram-mod-n-max",
        "64",
        "--top-k",
        "20",
    ]
    assert translate_ngram_mod_args(knobs, "new") == knobs
    assert translate_ngram_mod_args(knobs, None) == knobs
    assert translate_ngram_mod_args(knobs, "legacy") == [
        "--spec-ngram-size-n",
        "16",
        "--draft-min",
        "8",
        "--draft-max",
        "64",
        "--top-k",
        "20",
    ]
    assert translate_ngram_mod_args(knobs, "legacy", chain_with_mtp = True) == [
        "--spec-ngram-size-n",
        "16",
        "--top-k",
        "20",
    ]
    # A trailing flag with no value is left for llama-server to reject.
    assert translate_ngram_mod_args(["--spec-ngram-mod-n-max"], "legacy") == [
        "--spec-ngram-mod-n-max"
    ]


def test_the_launch_respells_user_ngram_mod_extras_last():
    """Source check: reaching the emit point needs a real binary."""
    import inspect

    from core.inference.llama_cpp import LlamaCppBackend

    src = inspect.getsource(LlamaCppBackend.load_model)
    emit = src[src.index("_emit_extra_args = self._strip_mmproj_args(") :]
    emit = emit[: emit.index("cmd.extend(str(a) for a in _emit_extra_args)")]
    assert "translate_ngram_mod_args(" in emit
    assert '_caps.get("ngram_mod_flavor")' in emit
    assert emit.index("_strip_device_extra_args") < emit.index("translate_ngram_mod_args(")
    assert "_extra_args_requests_mtp(" in emit[emit.index("translate_ngram_mod_args(") :]


def test_ngram_mod_underscore_spelling_is_respelled_too():
    from core.inference.llama_server_args import translate_ngram_mod_args
    assert translate_ngram_mod_args(
        ["--spec_ngram_mod_n_min", "8", "--spec_ngram_mod_n_match=4"], "legacy"
    ) == ["--draft-min", "8", "--spec-ngram-size-n", "4"]


def test_user_spec_type_with_mtp_counts_as_chained():
    from core.inference.llama_cpp import _child_spec_env, _extra_args_requests_mtp

    extras = ["--spec-type", "ngram-mod,draft-mtp", "--spec-ngram-mod-n-min", "48"]
    assert _extra_args_requests_mtp(extras, env = _child_spec_env(extras))
    assert not _extra_args_requests_mtp(["--spec-ngram-mod-n-min", "48"], env = {})


def test_owner_only_path_flags_names_each_file_option_once():
    args = [
        "--ctx-size",
        "4096",
        "--lora",
        "/a.gguf",
        "--lora",
        "/b.gguf",
        "--chat_template_file",
        "/t.jinja",
        "-jf",
        "/s.json",
        "--temp",
        "0.7",
    ]
    assert _lsa.owner_only_path_flags(args) == ["--lora", "--chat-template-file", "-jf"]
    assert _lsa.owner_only_path_flags(["--ctx-size", "4096", "-ngl", "99"]) == []
    assert _lsa.owner_only_path_flags(None) == []
    assert validate_extra_args(args) == args


@pytest.mark.parametrize("chain_with_mtp", [False, True])
def test_translate_ngram_mod_does_not_consume_a_following_flag(chain_with_mtp):
    # Under MTP the swallowed pair is dropped, leaving the next flag's value as a bare positional.
    from core.inference.llama_server_args import translate_ngram_mod_args, validate_extra_args

    args = validate_extra_args(
        ["--spec-type", "draft-mtp", "--spec-ngram-mod-n-min", "--top-k", "/restricted/model.gguf"]
    )
    out = translate_ngram_mod_args(args, "legacy", chain_with_mtp = chain_with_mtp)
    assert out[-2:] == ["--top-k", "/restricted/model.gguf"]
    validate_extra_args(out)


@pytest.mark.parametrize(
    "argv, env, auto",
    [
        ([], {}, True),
        (["--load-mode", "auto"], {}, True),
        (["--load-mode=auto"], {}, True),
        (["--load-mode", "none", "--load-mode", "auto"], {}, True),
        ([], {"LLAMA_ARG_LOAD_MODE": "auto"}, True),
        (["--load-mode", "auto"], {"LLAMA_ARG_LOAD_MODE": "mmap"}, True),
        (["--load-mode", "mmap"], {}, False),
        (["--load-mode", "none"], {}, False),
        ([], {"LLAMA_ARG_LOAD_MODE": "mmap"}, False),
        (["--mlock"], {}, False),
        (["--mmap"], {}, False),
        (["--no-mmap"], {}, False),
        ([], {"LLAMA_ARG_NO_MMAP": "0"}, False),
        ([], {"LLAMA_ARG_DIO": "1"}, False),
        (["--load-mode"], {}, True),
    ],
)
def test_load_mode_left_auto(argv, env, auto):
    assert _lsa.load_mode_left_auto(argv, env) is auto


def test_auto_reserves_ram_only_where_llama_cpp_resolves_it_to_none():
    assert _lsa.resolve_effective_load_state([], {}) == (False, False, False)
    assert _lsa.resolve_effective_load_state([], {}, auto_unmapped = True) == (False, True, False)
    assert _lsa.resolve_effective_memory_state(["--load-mode", "auto"], {}, auto_unmapped = True) == (
        False,
        True,
    )
    assert _lsa.resolve_effective_load_state(["--load-mode", "mmap"], {}, auto_unmapped = True) == (
        False,
        False,
        False,
    )
    assert _lsa.resolve_effective_load_state(["--load-mode", "dio"], {}, auto_unmapped = True) == (
        False,
        False,
        True,
    )


def test_the_pageable_rewrite_maps_an_unselected_mode_on_an_igpu():
    out, overridden = _lsa.force_pageable_load(["--fit", "on"], {}, auto_unmapped = True)
    assert out == ["--fit", "on", "--load-mode", "mmap"] and overridden
    assert _lsa.resolve_effective_memory_state(out, {}, auto_unmapped = True) == (False, False)
    # An inherited LLAMA_ARG_LOAD_MODE=auto loses to the appended argv.
    env = {"LLAMA_ARG_LOAD_MODE": "auto"}
    out, _ = _lsa.force_pageable_load([], env, auto_unmapped = True)
    assert _lsa.resolve_effective_memory_state(out, env, auto_unmapped = True) == (False, False)
    for argv, env in (
        (["--load-mode", "none"], {}),
        (["--no-mmap"], {}),
        ([], {"LLAMA_ARG_NO_MMAP": "1"}),
    ):
        out, overridden = _lsa.force_pageable_load(argv, env, auto_unmapped = True)
        assert overridden and out[-2:] == ["--load-mode", "mmap"], (argv, env, out)
        assert _lsa.resolve_effective_memory_state(out, env, auto_unmapped = True) == (False, False)
    assert _lsa.force_pageable_load(["--load-mode", "mlock"], {}, auto_unmapped = True)[0] == [
        "--load-mode",
        "mmap+mlock",
    ]
    assert _lsa.force_pageable_load([], {}) == ([], [])
    assert _lsa.force_pageable_load(["--load-mode", "mmap"], {}, auto_unmapped = True) == (
        ["--load-mode", "mmap"],
        [],
    )