llama : log the QSA maskless/masked route decision and why it was refused

[klucsik]

Overview

When a qwen4exp ubatch falls back from the maskless selected-key path to the masked route, the
server log stays silent, so an operator cannot tell a wrong-kernel route apart from a starved slot
or a cold PLE gather. We hit exactly this while measuring -np 2 serving on gfx1151: a
19,765-token request ran at 149.35 t/s (6.70 ms/tok) while a concurrent 104,661-token request held
876-912 t/s (1.18 ms/tok) on the other slot, same build and moment. Our first read blamed the
masked path (via graphs reused = 0 — a misread: n_reused is a cumulative context counter, so 0
is simply what the first task after load prints); it was actually cold-PLE I/O (243 MB/s disk-read
peak in the same window). Nothing in the server log could rule the mask out directly.

This PR turns the qwen4exp_use_block_selection() conjunction into a reason classifier returning
the first clause that refused the maskless path, and reports the route: LLAMA_LOG_DEBUG on every
decision (once per ubatch, at the existing qsa_inps per-ratio dedup), plus one LLAMA_LOG_INFO
line when the route or the refusing clause changes — rate-limited to 1 line / 5 s, keyed per memory
object (trunk and MTP draft refuse the path for different reasons, and a single global would toggle
on every rebuild). The original gate survives as a one-line wrapper, evaluating its clauses in
exactly the previous short-circuit order, so the boolean and the reason cannot disagree.
can_reuse() recomputes the same gate but does not log: a reused graph repeats an already-recorded
decision.

Measurements

Observability-only change: the route selection, tensors and kernels are untouched, so no
throughput, latency, memory-use or output movement is possible — that is why there are no
before/after llama-bench tables. The only runtime-visible effect is log volume at -lv >= 4,
which needs a gfx1151 run we could not perform here (see NOT verified).

Device:     Ryzen AI Max+ 395 / Framework Desktop        <- confirm mini-PC model
Memory:     128 GB LPDDR5X-8000
Power:      ryzenadj: STAPM 90 W, PPT fast 120 W, PPT slow 100 W, TCTL 85 C, CO all-core -20
BIOS:       UMA split <fill in: amdgpu BIOS carve on this box>
Kernel:     7.2.6-1-cachyos, amdgpu params: <fill in gttsize/ttm.pages_limit or "none">
Backend:    ROCm 10.x (klucsikkp/rocm-10.0-strix-llama image, retained-PM4 ROCr),
            HIP_LAUNCH_BLOCKING unset
Build:      Dockerfile.rocm-10.0-strix-llama flags: -DGGML_HIP=ON -DGGML_HIP_GRAPHS=ON
            -DGGML_HIP_NO_VMM=ON -DGGML_CUDA_FA=ON -DGPU_TARGETS=gfx1151 -DCMAKE_BUILD_TYPE=Release;
            this commit additionally compiled as a CPU object (g++ 14.2, -O1 -Wall)
Baseline:   7a9196dad (origin/master == branch parent, built & deployed in same session as the
            serving data quoted below)
Change:     aa6536531 (feat/qsa-route-log)
Model:      unsloth/Qwen3.8-Flash-Next-GGUF, UD-IQ4_XS

Baseline: n/a by construction — no compute path differs. Serving reference from this box on the
baseline commit (matched ini: -c 262144 -np 2 -b 4096 -ub 4096 -fa on -ctk/-ctv f16 -lm dio,
live traffic): solo pp chunk median 603 t/s.

After: n/a by construction; the branch changes only log statements. A 10-minute gfx1151 smoke
(-lv 4, text + one image burst) confirming the route lines appear as designed is listed as not
done below.

Correctness: exhaustive equivalence harness over the extracted gate logic: 570,240 input
combinations across every clause, including both n_kv boundaries (indexer_top_k + ratio - 1 and
16,777,216) — old_gate == (miss == nullptr) in all cases, 0 mismatches, and all 14 refusal
strings reachable at least once. Translation unit builds clean with -c -O1 -Wall (the only
warnings, two prefix.h unused-function ones, are present identically on pristine master).
test-backend-ops not run: no op or kernel touched. Logits/PPL not re-measured: graph outputs are
produced by the same tensors and kernels as before by construction. Harness source (<1 s to run)
available on request for CI.

Additional information

• Directly helps qwen4exp: GGML_ABORT ("maskless selected-key attention was not taken by a QSA kernel") on KV-cache exhaustion under --kv-unified with concurrent slots #85 (GGML_ABORT: maskless selected-key attention was not taken by a QSA kernel): the INFO line states which clause admitted the graph into maskless mode.
• Bounded tracing precedent: deepseek-v41 : add bounded runtime and correctness tracing #49. Route gate from qsa: fix n_stream>1 crash and enable maskless multi-sequence block selection #86; its perf from hip: optimize Qwen3.8-Flash-Next prefill on Strix Halo #91 — the matched A/B on this
  box showed pr-91 head at solo pp median 831-875 t/s vs 603 on master (full write-up offered
  as a comment on hip: optimize Qwen3.8-Flash-Next prefill on Strix Halo #91).
• Rate-limit rationale: text/image-alternating workloads flip the route as steady state; without
  the 5 s window the INFO would fire ~2x/request and train operators to ignore it.

Requirements

• I have read and agree with the contributing guidelines
• This change is Strix Halo specific, or justified by measurements on Strix Halo. General llama.cpp improvements
  belong in halo-box/llama.cpp instead — qwen4exp/QSA gates are
  fork-specific code, so this is Strix Halo specific by location, and motivated by gfx1151 serving data.
• AI usage disclosure: AGENT-AUTHORED — code, commit message and this description were written by a coding
  agent (Piclaw, qwen3.8-flash) under human review; the human owns the key, pushed the branch and files the PR.
  Assisted-by: trailer on the commit.
• What was NOT verified: no ROCm/GPU execution of this branch (the build sandbox has no amdgpu device) — so no
  live -lv 4 log-volume observation and no on-hardware smoke of the DBG/INF lines; no test-backend-ops (no op
  was touched); the equivalence proof covers the extracted gate logic as a standalone harness, not the linked
  llama binary; UMA/gtt values above are placeholders to fill in on the host.

Assisted-by: Piclaw (qwen3.8-flash)

[dzannotti]

Verified on Strix Halo (gfx1151, HIP), base 7a9196dad vs this PR, Qwen3.8-Flash-Next Q2_0, ABBA n=4:

	base	PR
pp512	651.0 ± 34.9	655.2 ± 39.5 (+0.7%)
pp2048	909.2 ± 19.6	912.0 ± 17.2 (+0.3%)
tg128	30.1	30.0
PPL, prose corpus, c6144	1.0034 ± 0.00100	1.0034 ± 0.00100 (identical)

The route logs appear as described (qsa route: maskless (...)). Two issues:

• Dedup key: the key is mctx_hyb, a per-batch memory context rather than a long-lived object, so the same route is logged again whenever a new context is created. It logged 4 times in one perplexity run (warmup plus 3 chunks), so "INFO only on change" depends on the allocator reusing addresses.
• Thread safety: the dedup map is a function-level static std::map with no lock, so two contexts building graphs on different threads race on it. thread_local or a mutex would fix it.

---

Comment generated via automated review of clanker Claude Code.

[dzannotti]

@klucsik with #115 merged is this PR still relevant?