From 25c5132b030c48a44319a3d40dd24fd573d752fe Mon Sep 17 00:00:00 2001
From: Xavier Karma <xavier@bongbetic.com>
Date: Fri, 6 Nov 2026 18:29:15 +0530
Subject: [PATCH] docs(models): mark ladder thresholds provisional until ticket
 19 is recorded

The rung cutoffs cite ticket 19's transcribe peaks, but ticket 19 is
still open and its measurement is not in this repository. The code and
test docstrings now say the numbers are provisional calibration to
replace, rather than evidence. Also formats the niri guard tests to the
project line length.
---
 src/vocalinux/speech_recognition/model_ladder.py | 16 +++++++++-------
 tests/test_injection_ladder.py                   |  8 ++++----
 tests/test_model_ladder.py                       |  7 ++++---
 3 files changed, 17 insertions(+), 14 deletions(-)

diff --git a/src/vocalinux/speech_recognition/model_ladder.py b/src/vocalinux/speech_recognition/model_ladder.py
index 3cd0892..dc4150a 100644
--- a/src/vocalinux/speech_recognition/model_ladder.py
+++ b/src/vocalinux/speech_recognition/model_ladder.py
@@ -8,12 +8,14 @@ Rungs (quantized Turbo first, small floor last)::
 
     large-v3-turbo-q8_0 -> large-v3-turbo-q5_0 -> small.en / small
 
-Thresholds derive from ticket #19's measured transcribe peaks (1132 MiB
-for q8_0, 846 MiB for q5_0) plus the 512 MiB desktop headroom from the
-locked baseline protocol
-(``scripts/measure_perf_baseline.py::recommend_thresholds``). The
-derivation is pinned by ``tests/test_model_ladder.py`` so a re-measure
-forces a threshold review.
+The thresholds are PROVISIONAL. They are the rule
+``scripts/measure_perf_baseline.py::recommend_thresholds`` applies (measured
+footprint plus the 512 MiB desktop headroom) to the transcribe peaks
+recorded for ticket #19 (1132 MiB for q8_0, 846 MiB for q5_0). Ticket #19
+is still open and its measurement is not recorded in this repository, so
+these numbers are the calibration to replace, not evidence. A re-measure
+changes the constants here, and ``tests/test_model_ladder.py`` pins them so
+that change is deliberate.
 
 Backend order follows the same readiness rule: CUDA ranks before Vulkan
 only when a complete architecture-matching CUDA toolkit is installed
@@ -39,7 +41,7 @@ LADDER_RUNGS: tuple[str, ...] = (DEFAULT_RUNG, LOW_MEMORY_RUNG)
 #: the baseline protocol adds to measured footprints.
 HEADROOM_MIB: float = 512.0
 
-#: Ticket #19 measured transcribe peaks (MiB) the thresholds below derive from.
+#: Provisional transcribe peaks (MiB) from ticket #19, not yet recorded in the repo.
 _MEASURED_Q8_0_PEAK_MIB: float = 1132.0
 _MEASURED_Q5_0_PEAK_MIB: float = 846.0
 
diff --git a/tests/test_injection_ladder.py b/tests/test_injection_ladder.py
index aefcead..ac52ac7 100644
--- a/tests/test_injection_ladder.py
+++ b/tests/test_injection_ladder.py
@@ -234,7 +234,9 @@ class TestNiriGuard:
     ) -> None:
         """The compositor-bridge predicate itself answers no on niri."""
         monkeypatch.setenv("XDG_CURRENT_DESKTOP", "niri")
-        monkeypatch.setattr(TextInjector, "_ibus_wayland_bridge_running", staticmethod(lambda: True))
+        monkeypatch.setattr(
+            TextInjector, "_ibus_wayland_bridge_running", staticmethod(lambda: True)
+        )
         injector = _bare_wayland_injector(environment=DesktopEnvironment.WAYLAND)
         assert injector._wayland_compositor_bridges_ibus() is False
 
@@ -263,9 +265,7 @@ class TestKeyEventToolOrder:
 
     @staticmethod
     def _tools(monkeypatch: pytest.MonkeyPatch, names: tuple) -> None:
-        monkeypatch.setattr(
-            "shutil.which", lambda cmd: f"/usr/bin/{cmd}" if cmd in names else None
-        )
+        monkeypatch.setattr("shutil.which", lambda cmd: f"/usr/bin/{cmd}" if cmd in names else None)
 
     def test_wtype_outranks_a_ready_ydotool(self, monkeypatch: pytest.MonkeyPatch) -> None:
         self._tools(monkeypatch, ("wtype", "ydotool"))
diff --git a/tests/test_model_ladder.py b/tests/test_model_ladder.py
index f747220..296b8ff 100644
--- a/tests/test_model_ladder.py
+++ b/tests/test_model_ladder.py
@@ -2,9 +2,10 @@
 
 All behavior is exercised with mocked probes and loaders: no GPU, no
 network, no hardware. The threshold-derivation test pins the rung
-thresholds to ticket #19's measured transcribe peaks (1132 MiB for q8_0,
-846 MiB for q5_0) plus the 512 MiB protocol headroom, so any re-measure
-forces a threshold review.
+thresholds to the provisional transcribe peaks (1132 MiB for q8_0, 846 MiB
+for q5_0, ticket #19, not yet recorded in the repo) plus the 512 MiB
+protocol headroom. Replacing them with a recorded measurement is a
+deliberate change to this test.
 """
 
 from unittest.mock import MagicMock, patch