@trillboards/edge-sdk 0.2.81 → 0.2.82

package/deploy/detector/tests/test_registry.py

@@ -0,0 +1,880 @@
+"""Residency, routing and refusal — with FAKE sessions and NO onnxruntime.
+
+WHAT THIS SUITE IS FOR. `docs/runbooks/sensing-model-library.md` §3 is the
+specification and every rule in it is a rule about what happens when a box
+cannot hold everything: which model answers a class, which one gets evicted,
+and — the load-bearing half — what the service says instead of answering when it
+cannot. None of that is reachable from the wire suite (which stubs the loader
+whole) or from the session suite (which needs numpy and skips on a bare
+interpreter).
+
+STDLIB ONLY, DELIBERATELY, exactly as `test_server.py` argues for the wire. The
+sessions here are two-line fakes and the "artifacts" are files of a few bytes,
+so every case runs on every CI runner with no ~128 MiB ONNX and no 50 MB
+runtime. A residency policy that could only be tested on a box with the models
+present is a residency policy nothing tests — and this one decides whether the
+box OOMs.
+"""
+
+from __future__ import annotations
+
+import tempfile
+import threading
+import unittest
+from pathlib import Path
+
+from trillboards_detector.detections import Detection, DetectionBatch, merge_batches
+from trillboards_detector.errors import DetectorNotReady, ModelContractError, UnknownClasses
+from trillboards_detector.labels import COCO91_CLASS_NAMES, RFDETR_MEDIUM, ModelVocabulary
+from trillboards_detector.registry import (
+    STATE_ABSENT,
+    STATE_IDLE,
+    STATE_READY,
+    STATE_UNAVAILABLE,
+    ModelEntry,
+    ModelRegistry,
+)
+
+MB = 1024 * 1024
+
+#: A general detector standing in for `rfdetr_medium`: same shape, tiny map, so
+#: a fixture that needs `person` and `car` does not carry eighty names.
+GENERAL = ModelVocabulary(
+    model_name="general",
+    slot_names={1: "person", 3: "car"},
+    logit_slots=91,
+    approx_ram_bytes=600 * MB,
+)
+
+#: A PPE specialist — the §3 worked example. It ALSO emits `person`, which is
+#: the ambiguity catalogue order exists to resolve.
+PPE = ModelVocabulary(
+    model_name="ppe",
+    slot_names={0: "person", 1: "glove", 2: "hairnet"},
+    logit_slots=3,
+    approx_ram_bytes=400 * MB,
+)
+
+#: A third specialist, so eviction has something to choose between.
+SMALL_OBJECT = ModelVocabulary(
+    model_name="small_object",
+    slot_names={0: "rodent"},
+    logit_slots=1,
+    approx_ram_bytes=400 * MB,
+)
+
+
+class FakeSpec:
+    width = 576
+    height = 576
+    num_classes = 91
+    providers = ["CPUExecutionProvider"]
+
+
+class FakeSession:
+    """One resident model. Records what it was asked and by whom."""
+
+    def __init__(self, vocabulary: ModelVocabulary, raises=None):
+        self.vocabulary = vocabulary
+        self.model_name = vocabulary.model_name
+        self.spec = FakeSpec()
+        self.calls: "list[tuple]" = []
+        self.closed = False
+        self._raises = raises
+
+    def detect(self, jpeg, min_confidence, wanted):
+        self.calls.append((jpeg, min_confidence, wanted))
+        if self._raises is not None:
+            raise self._raises
+        return DetectionBatch(
+            detections=[Detection(f"{self.model_name}-hit", 0.9, 1.0, 1.0, 2.0, 2.0)],
+            inference_ms=10.0,
+            total_ms=12.0,
+            models=[self.model_name],
+        )
+
+    def __del__(self):  # pragma: no cover - refcount observation only
+        self.closed = True
+
+
+class RegistryCase(unittest.TestCase):
+    """Builds a registry over real files in a temp dir, with fake sessions."""
+
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.tmp.cleanup)
+        self.root = Path(self.tmp.name)
+        self.logs: "list[str]" = []
+        self.built: "list[str]" = []
+        self.probed: "list[str]" = []
+        self.factory_raises: "dict[str, Exception]" = {}
+        self.probe_raises: "dict[str, Exception]" = {}
+        self.session_raises: "dict[str, Exception]" = {}
+        self.sessions: "dict[str, FakeSession]" = {}
+        #: A monotonic clock we control, so LRU order is a fact and not a race.
+        self.now = 0.0
+
+    def tick(self, by: float = 1.0) -> None:
+        self.now += by
+
+    def write_artifact(self, name: str, payload: bytes = b"onnx") -> Path:
+        path = self.root / "models" / name / "model.onnx"
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_bytes(payload)
+        return path
+
+    def remove_artifact(self, name: str) -> None:
+        (self.root / "models" / name / "model.onnx").unlink()
+
+    def _factory(self, entry: ModelEntry):
+        self.built.append(entry.name)
+        boom = self.factory_raises.get(entry.name)
+        if boom is not None:
+            raise boom
+        session = FakeSession(entry.vocabulary, self.session_raises.get(entry.name))
+        self.sessions[entry.name] = session
+        return session
+
+    def _probe(self, session) -> None:
+        self.probed.append(session.model_name)
+        boom = self.probe_raises.get(session.model_name)
+        if boom is not None:
+            raise boom
+
+    def registry(
+        self,
+        vocabularies,
+        pinned: str,
+        budget_mb: "int | None" = 1536,
+    ) -> ModelRegistry:
+        """Every case INJECTS a ceiling, because the service owns none.
+
+        `budget_mb=None` is the state where nobody has told it one — a state,
+        not a default — and `TestNoCeilingWasInjected` is what covers it.
+        """
+        entries = [
+            ModelEntry(v, self.root / "models" / v.model_name / "model.onnx", pinned=v.model_name == pinned)
+            for v in vocabularies
+        ]
+        return ModelRegistry(
+            entries=entries,
+            session_factory=self._factory,
+            probe=self._probe,
+            ram_budget_bytes=None if budget_mb is None else budget_mb * MB,
+            log=self.logs.append,
+            clock=lambda: self.now,
+        )
+
+
+class TestTwoModelsAnswerOneRequest(RegistryCase):
+    """§3: "A request spanning two models runs both and merges." """
+
+    def test_a_request_spanning_two_models_runs_both_and_merges(self):
+        self.write_artifact("general")
+        self.write_artifact("ppe")
+        reg = self.registry([GENERAL, PPE], pinned="general")
+        reg.refresh()
+
+        wanted = reg.resolve_classes(["person", "glove"])
+        batch = reg.detect(b"jpeg", 0.25, wanted)
+
+        # BOTH ran, in catalogue order, and both answers are in the result.
+        self.assertEqual(batch.models, ["general", "ppe"])
+        self.assertEqual([d.label for d in batch.detections], ["general-hit", "ppe-hit"])
+        # `person` went to the GENERAL model even though `ppe` also emits it —
+        # catalogue order breaks the tie, and the 98.8/98.8 is a claim about
+        # the general model's `person`, not about the concept.
+        self.assertEqual(self.sessions["general"].calls[0][2], {"person"})
+        self.assertEqual(self.sessions["ppe"].calls[0][2], {"glove"})
+
+    def test_the_merged_timing_is_the_sum_because_they_run_serially(self):
+        self.write_artifact("general")
+        self.write_artifact("ppe")
+        reg = self.registry([GENERAL, PPE], pinned="general")
+        reg.refresh()
+        batch = reg.detect(b"jpeg", 0.25, reg.resolve_classes(["person", "glove"]))
+        self.assertEqual(batch.inference_ms, 20.0)
+
+    def test_the_union_vocabulary_is_what_a_caller_may_ask_for(self):
+        """THE PIECE THAT MAKES A SPECIALIST EXPRESSIBLE. `glove` used to come
+        back `unknown` against a hardcoded COCO-91 set, so publishing a PPE
+        model would have changed nothing at the service."""
+        self.write_artifact("general")
+        self.write_artifact("ppe")
+        reg = self.registry([GENERAL, PPE], pinned="general")
+        reg.refresh()
+        self.assertEqual(
+            reg.class_index().class_names, frozenset({"person", "car", "glove", "hairnet"})
+        )
+        # And they fold the way a profile writes them: `sensing_profiles.classes`
+        # is LLM prose, so `Glove` and `HAIRNET` must reach the same names.
+        self.assertEqual(reg.resolve_classes(["Glove", "HAIRNET"]), {"glove", "hairnet"})
+
+    def test_absent_classes_asks_each_model_only_for_what_it_owns(self):
+        """"Every class" must not double-report an overlapping one.
+
+        Running each model over its whole vocabulary would return two `person`
+        boxes for one person — from the general model and from PPE — and nothing
+        downstream could tell that from two people.
+        """
+        self.write_artifact("general")
+        self.write_artifact("ppe")
+        reg = self.registry([GENERAL, PPE], pinned="general")
+        reg.refresh()
+        reg.detect(b"jpeg", 0.25, None)
+        # The general model owns its whole vocabulary, so it gets `None` — the
+        # same object the single-model service always passed.
+        self.assertIsNone(self.sessions["general"].calls[0][2])
+        # PPE gets everything EXCEPT the `person` the general model owns.
+        self.assertEqual(self.sessions["ppe"].calls[0][2], {"glove", "hairnet"})
+
+    def test_a_partly_unknown_list_is_a_refusal_not_the_known_half(self):
+        """ANY unknown is a refusal, not just all of them.
+
+        `["person", "shoplifter"]` used to proceed on `person` and drop
+        `shoplifter` silently, so a profile asking about shoplifting got person
+        counts and no signal that its actual question was discarded. The partial
+        case is the dangerous one and it becomes the COMMON one the moment
+        specialists exist — a PPE profile naming `glove` alongside `person` on a
+        box with no PPE model.
+        """
+        self.write_artifact("general")
+        self.write_artifact("ppe")
+        reg = self.registry([GENERAL, PPE], pinned="general")
+        reg.refresh()
+        with self.assertRaises(UnknownClasses) as caught:
+            reg.resolve_classes(["person", "shoplifter"])
+        self.assertEqual(caught.exception.unknown, ["shoplifter"])
+
+
+class TestLazyLoadAndEviction(RegistryCase):
+    """§3: lazy, with LRU eviction under a stated RAM budget."""
+
+    def test_a_specialist_is_not_loaded_until_its_classes_are_asked_for(self):
+        self.write_artifact("general")
+        self.write_artifact("ppe")
+        reg = self.registry([GENERAL, PPE], pinned="general")
+        reg.refresh()
+        # The watcher loaded the PINNED model and nothing else.
+        self.assertEqual(self.built, ["general"])
+        self.assertEqual(reg.snapshot()["resident_models"], ["general"])
+
+        reg.detect(b"jpeg", 0.25, reg.resolve_classes(["glove"]))
+        self.assertEqual(self.built, ["general", "ppe"])
+
+    def test_eviction_under_a_budget_that_forces_it(self):
+        """1,000 MiB holds the pinned 600 plus ONE 400 MiB specialist, never two.
+
+        The LRU choice is a fact here, not a race: the clock is injected.
+        """
+        for name in ("general", "ppe", "small_object"):
+            self.write_artifact(name)
+        reg = self.registry([GENERAL, PPE, SMALL_OBJECT], pinned="general", budget_mb=1000)
+        reg.refresh()
+
+        self.tick()
+        reg.detect(b"jpeg", 0.25, reg.resolve_classes(["glove"]))
+        self.assertEqual(sorted(reg.snapshot()["resident_models"]), ["general", "ppe"])
+
+        self.tick()
+        reg.detect(b"jpeg", 0.25, reg.resolve_classes(["rodent"]))
+        snap = reg.snapshot()
+        # `ppe` was the least recently used non-pinned model, so it went.
+        self.assertEqual(sorted(snap["resident_models"]), ["general", "small_object"])
+        self.assertEqual(snap["models"]["ppe"]["state"], STATE_IDLE)
+        self.assertEqual(snap["models"]["ppe"]["evictions"], 1)
+        self.assertLessEqual(snap["ram_resident_bytes"], snap["ram_budget_bytes"])
+
+    def test_the_pinned_model_is_never_the_one_evicted(self):
+        for name in ("general", "ppe", "small_object"):
+            self.write_artifact(name)
+        reg = self.registry([GENERAL, PPE, SMALL_OBJECT], pinned="general", budget_mb=1000)
+        reg.refresh()
+        self.tick()
+        reg.detect(b"jpeg", 0.25, reg.resolve_classes(["glove"]))
+        self.tick()
+        reg.detect(b"jpeg", 0.25, reg.resolve_classes(["rodent"]))
+        self.assertIn("general", reg.snapshot()["resident_models"])
+
+    def test_an_evicted_model_reloads_on_the_next_request_for_its_classes(self):
+        for name in ("general", "ppe", "small_object"):
+            self.write_artifact(name)
+        reg = self.registry([GENERAL, PPE, SMALL_OBJECT], pinned="general", budget_mb=1000)
+        reg.refresh()
+        self.tick()
+        reg.detect(b"jpeg", 0.25, reg.resolve_classes(["glove"]))
+        self.tick()
+        reg.detect(b"jpeg", 0.25, reg.resolve_classes(["rodent"]))
+        self.assertNotIn("ppe", reg.snapshot()["resident_models"])
+
+        self.tick()
+        batch = reg.detect(b"jpeg", 0.25, reg.resolve_classes(["glove"]))
+        # It came back, it was PROVED again, and it answered.
+        self.assertEqual(self.built.count("ppe"), 2)
+        self.assertEqual(self.probed.count("ppe"), 2)
+        self.assertEqual(batch.models, ["ppe"])
+        self.assertEqual([d.label for d in batch.detections], ["ppe-hit"])
+
+    def test_an_evicted_class_is_still_requestable(self):
+        """Presence, not residency, decides the offer.
+
+        Gating on residency would make the SAME profile 400 or 200 depending on
+        what ran a minute ago.
+        """
+        for name in ("general", "ppe", "small_object"):
+            self.write_artifact(name)
+        reg = self.registry([GENERAL, PPE, SMALL_OBJECT], pinned="general", budget_mb=1000)
+        reg.refresh()
+        self.tick()
+        reg.detect(b"jpeg", 0.25, reg.resolve_classes(["glove"]))
+        self.tick()
+        reg.detect(b"jpeg", 0.25, reg.resolve_classes(["rodent"]))
+        self.assertNotIn("ppe", reg.snapshot()["resident_models"])
+        self.assertIn("glove", reg.class_index().class_names)
+
+    def test_a_set_that_cannot_fit_is_refused_with_what_did_not_fit(self):
+        """§2: "report what it could not fit rather than silently dropping it."
+
+        The alternative — answering with the models that DID fit — is a thinner
+        frame indistinguishable downstream from a quieter venue.
+        """
+        for name in ("general", "ppe", "small_object"):
+            self.write_artifact(name)
+        reg = self.registry([GENERAL, PPE, SMALL_OBJECT], pinned="general", budget_mb=1000)
+        reg.refresh()
+        with self.assertRaises(DetectorNotReady) as caught:
+            reg.detect(b"jpeg", 0.25, reg.resolve_classes(["glove", "rodent"]))
+        message = str(caught.exception)
+        self.assertIn("ppe", message)
+        self.assertIn("small_object", message)
+        self.assertIn("budget", message)
+        # NOTHING RAN, and neither specialist was even BUILT — refusing after
+        # allocating half the set would leave the box over budget for nothing.
+        self.assertEqual(self.built, ["general"])
+        self.assertNotIn("ppe", self.sessions)
+
+    def test_a_ceiling_that_cannot_hold_the_pinned_model_is_refused_at_construction(self):
+        """Permanently unavailable is a different problem from constrained, and
+        it must be visible at start rather than on the first frame."""
+        with self.assertRaisesRegex(ValueError, "cannot hold the pinned model"):
+            self.registry([GENERAL, PPE], pinned="general", budget_mb=100)
+
+    def test_eviction_is_reported_as_abnormal_not_as_routine(self):
+        """A box evicting at all is OVERSUBSCRIBED against what it was allocated,
+        and the authority that set the ceiling needs to see that. A service
+        quietly thrashing under one looks exactly like a service working fine —
+        which is the failure shape this whole tree keeps catching."""
+        for name in ("general", "ppe", "small_object"):
+            self.write_artifact(name)
+        reg = self.registry([GENERAL, PPE, SMALL_OBJECT], pinned="general", budget_mb=1000)
+        reg.refresh()
+        self.assertEqual(reg.snapshot()["evictions"], 0)
+
+        self.tick()
+        reg.detect(b"jpeg", 0.25, reg.resolve_classes(["glove"]))
+        self.tick()
+        reg.detect(b"jpeg", 0.25, reg.resolve_classes(["rodent"]))
+
+        self.assertEqual(reg.snapshot()["evictions"], 1)
+        self.assertTrue(
+            any("WARNING" in line and "oversubscribed" in line for line in self.logs),
+            f"eviction was not logged as abnormal: {self.logs}",
+        )
+
+
+class TestNoCeilingWasInjected(RegistryCase):
+    """`None` means NOBODY TOLD US — it is not "unlimited" and not a default.
+
+    The allocation authority is server-side: `selectModelForDeviceTier` sizes a
+    model from `deviceRamMb`/`deviceTier` and the model manifest gates on
+    `min_ram_mb`. A ceiling chosen inside this service would be a SECOND
+    authority that cannot see the first — the `yolov8_nano` shape, advertised by
+    one component and unloadable by another.
+    """
+
+    def test_the_pinned_model_still_loads_and_answers(self):
+        """Holding what the server already told us to hold is the mechanism
+        doing its job, not a portfolio decision. Without this the whole detector
+        would go dark on every box that has not been told a ceiling."""
+        self.write_artifact("general")
+        self.write_artifact("ppe")
+        reg = self.registry([GENERAL, PPE], pinned="general", budget_mb=None)
+        reg.refresh()
+        self.assertEqual(reg.snapshot()["resident_models"], ["general"])
+        batch = reg.detect(b"jpeg", 0.25, reg.resolve_classes(["person"]))
+        self.assertEqual(batch.models, ["general"])
+
+    def test_making_a_SECOND_model_resident_is_refused_and_says_why(self):
+        self.write_artifact("general")
+        self.write_artifact("ppe")
+        reg = self.registry([GENERAL, PPE], pinned="general", budget_mb=None)
+        reg.refresh()
+        with self.assertRaises(DetectorNotReady) as caught:
+            reg.detect(b"jpeg", 0.25, reg.resolve_classes(["glove"]))
+        message = str(caught.exception)
+        self.assertIn("no RAM ceiling was injected", message)
+        self.assertIn("will not invent one", message)
+        self.assertIn("selectModelForDeviceTier", message)
+        # And nothing was allocated on the way to refusing.
+        self.assertEqual(self.built, ["general"])
+
+    def test_health_says_the_ceiling_is_absent_rather_than_showing_a_number(self):
+        """A reader must be able to SEE that no authority has spoken. A number
+        here would be indistinguishable from an injected one."""
+        self.write_artifact("general")
+        reg = self.registry([GENERAL, PPE], pinned="general", budget_mb=None)
+        reg.refresh()
+        snap = reg.snapshot()
+        self.assertIsNone(snap["ram_budget_bytes"])
+        self.assertFalse(snap["ram_ceiling_injected"])
+
+    def test_an_injected_ceiling_is_reported_as_injected(self):
+        self.write_artifact("general")
+        reg = self.registry([GENERAL, PPE], pinned="general", budget_mb=1024)
+        reg.refresh()
+        snap = reg.snapshot()
+        self.assertEqual(snap["ram_budget_bytes"], 1024 * MB)
+        self.assertTrue(snap["ram_ceiling_injected"])
+
+    def test_a_non_positive_ceiling_is_refused_rather_than_treated_as_absent(self):
+        """`0` is somebody telling us something wrong, which is a different
+        problem from nobody telling us anything."""
+        for bad in (0, -1):
+            with self.subTest(bad=bad):
+                with self.assertRaisesRegex(ValueError, "must be positive"):
+                    self.registry([GENERAL], pinned="general", budget_mb=bad)
+
+
+class TestResidentFootprintIsMeasured(RegistryCase):
+    """The column the server does not have, produced per load.
+
+    `min_ram_mb` is a GATE, `model_size_mb` is a FILE SIZE, and the quantity
+    portfolio admission needs — resident footprint — is neither. This measures
+    it and REPORTS it; it must never feed admission, or the service is back to
+    being a second authority using numbers the first cannot see.
+    """
+
+    def test_a_load_records_a_footprint_and_names_the_instrument(self):
+        # SKIP ON THE PLATFORM, NEVER ON THE RESULT. Skipping because the field
+        # is absent would make this pass for the one reason it exists to
+        # catch — a measurement that stopped happening. So the skip predicate
+        # asks the platform directly, and an absent field is then a FAILURE.
+        from trillboards_detector.registry import read_process_rss
+
+        if read_process_rss() is None:  # pragma: no cover - no stdlib source
+            self.skipTest("no stdlib RSS source on this platform")
+
+        self.write_artifact("general")
+        reg = self.registry([GENERAL], pinned="general")
+        reg.refresh()
+        row = reg.snapshot()["models"]["general"]
+        self.assertIn(
+            "rss_delta_bytes",
+            row,
+            "the load recorded no footprint although this platform HAS an RSS source",
+        )
+        self.assertIsInstance(row["rss_delta_bytes"], int)
+        self.assertGreaterEqual(row["rss_delta_bytes"], 0)
+        # NAMED, because the three platforms do not answer the same question:
+        # `rusage-maxrss` is a high-water mark, so its delta is a lower bound
+        # and 0 is legitimate; the other two are current RSS.
+        self.assertIn(row["rss_source"], ("proc-statm", "psapi-workingset", "rusage-maxrss"))
+
+    def test_the_measurement_never_decides_admission(self):
+        """A fake session that allocates nothing must still be admitted on its
+        COMMITTED cost — otherwise a box would admit a model it has no committed
+        figure for, using a number only this service can see."""
+        self.write_artifact("general")
+        self.write_artifact("ppe")
+        # 1000 MiB holds the committed 600 + 400 exactly, and the fakes allocate
+        # essentially nothing. Admission must follow the committed figures.
+        reg = self.registry([GENERAL, PPE], pinned="general", budget_mb=1000)
+        reg.refresh()
+        reg.detect(b"jpeg", 0.25, reg.resolve_classes(["glove"]))
+        snap = reg.snapshot()
+        self.assertEqual(snap["ram_resident_bytes"], 1000 * MB)
+        self.assertEqual(snap["models"]["ppe"]["approx_ram_bytes"], 400 * MB)
+
+    def test_a_failed_load_leaves_no_footprint_behind(self):
+        self.write_artifact("general")
+        self.write_artifact("ppe")
+        self.probe_raises["ppe"] = RuntimeError("no forward pass")
+        reg = self.registry([GENERAL, PPE], pinned="general")
+        reg.refresh()
+        with self.assertRaises(DetectorNotReady):
+            reg.detect(b"jpeg", 0.25, reg.resolve_classes(["glove"]))
+        self.assertNotIn("rss_delta_bytes", reg.snapshot()["models"]["ppe"])
+
+    def test_the_rss_reader_answers_or_says_it_cannot(self):
+        from trillboards_detector.registry import read_process_rss
+
+        reading = read_process_rss()
+        self.assertIsNotNone(reading, "no stdlib RSS source at all on this platform")
+        value, source = reading
+        self.assertGreater(value, 0)
+        self.assertIn(source, ("proc-statm", "psapi-workingset", "rusage-maxrss"))
+
+
+class TestDownIsNeverEmpty(RegistryCase):
+    """The single failure this whole component exists to prevent."""
+
+    def test_a_model_whose_file_is_missing_refuses_rather_than_answering(self):
+        self.write_artifact("general")
+        # `ppe`'s artifact is never written — the OTA has not landed.
+        reg = self.registry([GENERAL, PPE], pinned="general")
+        reg.refresh()
+
+        snap = reg.snapshot()
+        self.assertEqual(snap["models"]["ppe"]["state"], STATE_ABSENT)
+        # Its classes are NOT offered, so §4 rule 5 holds by construction: a
+        # committed vocabulary with no artifact advertises nothing.
+        self.assertNotIn("glove", reg.class_index().class_names)
+
+        with self.assertRaises(UnknownClasses) as caught:
+            reg.resolve_classes(["glove"])
+        # And the message separates "no build ever heard of this" from "the
+        # artifact has not arrived", which are opposite problems.
+        self.assertIn("ppe", caught.exception.detail)
+        self.assertIn("has not arrived yet", caught.exception.detail)
+
+    def test_an_artifact_that_disappears_after_a_request_refuses_mid_flight(self):
+        self.write_artifact("general")
+        self.write_artifact("ppe")
+        reg = self.registry([GENERAL, PPE], pinned="general")
+        reg.refresh()
+        wanted = reg.resolve_classes(["glove"])
+        self.remove_artifact("ppe")
+        with self.assertRaisesRegex(DetectorNotReady, "not found"):
+            reg.detect(b"jpeg", 0.25, wanted)
+
+    def test_a_model_that_fails_to_load_is_unavailable_with_the_reason(self):
+        self.write_artifact("general")
+        self.write_artifact("ppe")
+        self.factory_raises["ppe"] = ModelContractError("model has 4 class slots")
+        reg = self.registry([GENERAL, PPE], pinned="general")
+        reg.refresh()
+        with self.assertRaises(DetectorNotReady) as caught:
+            reg.detect(b"jpeg", 0.25, reg.resolve_classes(["glove"]))
+        self.assertIn("does not match the detector contract", str(caught.exception))
+        self.assertEqual(reg.snapshot()["models"]["ppe"]["state"], STATE_UNAVAILABLE)
+
+    def test_a_session_that_constructs_but_cannot_infer_is_not_ready(self):
+        """PROVE IT, PER MODEL. `/v1/models` answers 200 without ever building
+        an engine, which is how a UTF-8 BOM 500'd every frame on every Windows
+        connector while two health checks passed."""
+        self.write_artifact("general")
+        self.write_artifact("ppe")
+        self.probe_raises["ppe"] = RuntimeError("ORT exploded on the probe frame")
+        reg = self.registry([GENERAL, PPE], pinned="general")
+        reg.refresh()
+        with self.assertRaises(DetectorNotReady) as caught:
+            reg.detect(b"jpeg", 0.25, reg.resolve_classes(["glove"]))
+        self.assertIn("probe inference failed", str(caught.exception))
+        self.assertEqual(reg.snapshot()["models"]["ppe"]["state"], STATE_UNAVAILABLE)
+        # The SESSION was built. Only the probe refused it, which is the whole
+        # point of running one.
+        self.assertIn("ppe", self.built)
+
+    def test_the_pinned_model_is_probed_before_it_is_called_ready(self):
+        self.write_artifact("general")
+        self.probe_raises["general"] = RuntimeError("no forward pass")
+        reg = self.registry([GENERAL], pinned="general")
+        reg.refresh()
+        self.assertEqual(reg.snapshot()["pinned_state"], STATE_UNAVAILABLE)
+
+    def test_one_model_of_two_failing_costs_the_whole_request(self):
+        """ALL OR NOTHING. Answering with the model that DID work is a thinner
+        frame nothing downstream can distinguish from a quieter venue."""
+        self.write_artifact("general")
+        self.write_artifact("ppe")
+        self.session_raises["ppe"] = RuntimeError("ORT exploded")
+        reg = self.registry([GENERAL, PPE], pinned="general")
+        reg.refresh()
+        with self.assertRaises(RuntimeError):
+            reg.detect(b"jpeg", 0.25, reg.resolve_classes(["person", "glove"]))
+        self.assertEqual(reg.snapshot()["models"]["ppe"]["detect_failures"], 1)
+
+    def test_a_failed_plan_does_not_leave_a_model_pinned_in_flight(self):
+        """A leak that only appears on the failure path is the kind nothing
+        notices: the first model would stay unevictable forever, so the budget
+        would silently shrink by one model per broken artifact."""
+        self.write_artifact("general")
+        self.write_artifact("ppe")
+        self.probe_raises["ppe"] = RuntimeError("no forward pass")
+        reg = self.registry([GENERAL, PPE], pinned="general")
+        reg.refresh()
+        with self.assertRaises(DetectorNotReady):
+            reg.detect(b"jpeg", 0.25, reg.resolve_classes(["person", "glove"]))
+        # `general` was acquired first and must have been given back.
+        self.assertEqual(reg._states["general"].in_flight, 0)
+
+    def test_merging_no_batches_raises_rather_than_returning_empty(self):
+        with self.assertRaisesRegex(ValueError, "503"):
+            merge_batches([])
+
+
+class TestSnapshotIsCheapAndHonest(RegistryCase):
+    """`/health` reports which models are resident and must not load one."""
+
+    def test_the_snapshot_loads_nothing_and_infers_nothing(self):
+        self.write_artifact("general")
+        self.write_artifact("ppe")
+        reg = self.registry([GENERAL, PPE], pinned="general")
+        reg.refresh()
+        built_before = list(self.built)
+
+        for _ in range(5):
+            snap = reg.snapshot()
+
+        self.assertEqual(self.built, built_before, "a health probe built a session")
+        self.assertEqual(self.sessions["general"].calls, [], "a health probe ran inference")
+        # It still reported the truth about residency while it was at it.
+        self.assertEqual(snap["resident_models"], ["general"])
+        self.assertEqual(snap["models"]["ppe"]["state"], STATE_IDLE)
+        self.assertEqual(snap["models"]["ppe"]["resident"], False)
+
+    def test_the_snapshot_names_every_catalogue_model_and_the_budget(self):
+        self.write_artifact("general")
+        reg = self.registry([GENERAL, PPE], pinned="general", budget_mb=1024)
+        reg.refresh()
+        snap = reg.snapshot()
+        self.assertEqual(sorted(snap["models"]), ["general", "ppe"])
+        self.assertEqual(snap["ram_budget_bytes"], 1024 * MB)
+        self.assertEqual(snap["ram_resident_bytes"], 600 * MB)
+        self.assertEqual(snap["models"]["general"]["state"], STATE_READY)
+        self.assertTrue(snap["models"]["general"]["pinned"])
+        self.assertFalse(snap["models"]["ppe"]["pinned"])
+        # A model whose artifact has not landed contributes no known class.
+        self.assertEqual(snap["known_class_count"], 2)
+
+    def test_drops_are_counted_per_model_never_only_in_aggregate(self):
+        """`telemetry-producer-substrate.md`: grade a column PER PRODUCER. One
+        specialist dropping everything it detects must not be averaged into
+        silence by the general model's zero."""
+        self.write_artifact("general")
+        self.write_artifact("ppe")
+        reg = self.registry([GENERAL, PPE], pinned="general")
+        reg.refresh()
+
+        class Dropping(FakeSession):
+            def detect(self, jpeg, min_confidence, wanted):
+                batch = super().detect(jpeg, min_confidence, wanted)
+                batch.unnamed_class_dropped = 3
+                return batch
+
+        reg._states["ppe"].session = Dropping(PPE)
+        reg._states["ppe"].state = STATE_READY
+        reg._states["ppe"].stamp = (4, 0)
+        self.sessions["ppe"] = reg._states["ppe"].session
+        reg._states["ppe"].stamp = (self.root / "models" / "ppe" / "model.onnx").stat().st_size, (
+            self.root / "models" / "ppe" / "model.onnx"
+        ).stat().st_mtime_ns
+
+        reg.detect(b"jpeg", 0.25, reg.resolve_classes(["person", "glove"]))
+        snap = reg.snapshot()
+        self.assertEqual(snap["models"]["ppe"]["unnamed_class_dropped"], 3)
+        self.assertEqual(snap["models"]["general"]["unnamed_class_dropped"], 0)
+        self.assertEqual(snap["unnamed_class_dropped"], 3)
+
+
+class TestOtaAndPresence(RegistryCase):
+    """The artifact arrives, changes and goes away with nobody restarting us."""
+
+    def test_a_specialist_that_arrives_later_widens_the_vocabulary(self):
+        self.write_artifact("general")
+        reg = self.registry([GENERAL, PPE], pinned="general")
+        reg.refresh()
+        self.assertNotIn("glove", reg.class_index().class_names)
+
+        self.write_artifact("ppe")
+        reg.refresh()
+        self.assertIn("glove", reg.class_index().class_names)
+        # Arriving does not load it. Lazy means lazy.
+        self.assertEqual(self.built, ["general"])
+
+    def test_a_changed_artifact_drops_the_session_so_the_next_request_reloads(self):
+        self.write_artifact("general")
+        self.write_artifact("ppe")
+        reg = self.registry([GENERAL, PPE], pinned="general")
+        reg.refresh()
+        reg.detect(b"jpeg", 0.25, reg.resolve_classes(["glove"]))
+        self.assertIn("ppe", reg.snapshot()["resident_models"])
+
+        self.write_artifact("ppe", b"a different and longer onnx")
+        reg.refresh()
+        self.assertNotIn("ppe", reg.snapshot()["resident_models"])
+        # Rebuilding a specialist from the WATCHER would be an allocation made
+        # outside a request that could have been refused for not fitting.
+        self.assertEqual(self.built.count("ppe"), 1)
+
+        reg.detect(b"jpeg", 0.25, reg.resolve_classes(["glove"]))
+        self.assertEqual(self.built.count("ppe"), 2)
+
+    def test_a_changed_pinned_artifact_reloads_from_the_watcher(self):
+        self.write_artifact("general")
+        reg = self.registry([GENERAL], pinned="general")
+        reg.refresh()
+        self.write_artifact("general", b"a different and longer onnx")
+        reg.refresh()
+        self.assertEqual(self.built.count("general"), 2)
+        self.assertEqual(reg.snapshot()["pinned_state"], STATE_READY)
+
+    def test_a_failed_load_is_not_retried_every_poll_on_the_same_bytes(self):
+        """Rebuilding a session that cannot work, per poll, forever, is not a
+        retry policy. The stamp moves when `ModelManager` rewrites the file, and
+        that is the event worth reacting to."""
+        self.write_artifact("general")
+        self.factory_raises["general"] = RuntimeError("corrupt")
+        reg = self.registry([GENERAL], pinned="general")
+        for _ in range(5):
+            reg.refresh()
+        self.assertEqual(self.built.count("general"), 1)
+
+        self.write_artifact("general", b"a repaired and longer onnx")
+        del self.factory_raises["general"]
+        reg.refresh()
+        self.assertEqual(self.built.count("general"), 2)
+        self.assertEqual(reg.snapshot()["pinned_state"], STATE_READY)
+
+    def test_a_zero_byte_artifact_is_absent_not_present(self):
+        """`ModelManager` writes `.tmp` then renames, but a truncated file on a
+        full disk is a real state and it is not a model."""
+        self.write_artifact("general", b"")
+        reg = self.registry([GENERAL], pinned="general")
+        reg.refresh()
+        self.assertEqual(reg.snapshot()["pinned_state"], STATE_ABSENT)
+        self.assertEqual(self.built, [])
+
+
+class TestConcurrency(RegistryCase):
+    """Two requests must not each admit a model and together exceed the budget."""
+
+    def test_a_model_with_a_request_in_flight_is_not_evicted(self):
+        for name in ("general", "ppe", "small_object"):
+            self.write_artifact(name)
+        reg = self.registry([GENERAL, PPE, SMALL_OBJECT], pinned="general", budget_mb=1000)
+        reg.refresh()
+
+        entered = threading.Event()
+        release = threading.Event()
+
+        class Blocking(FakeSession):
+            def detect(inner, jpeg, min_confidence, wanted):
+                entered.set()
+                release.wait(10)
+                return super().detect(jpeg, min_confidence, wanted)
+
+        self.tick()
+        reg.detect(b"jpeg", 0.25, reg.resolve_classes(["glove"]))
+        reg._states["ppe"].session = Blocking(PPE)
+        self.sessions["ppe"] = reg._states["ppe"].session
+
+        errors: "list[BaseException]" = []
+
+        def slow():
+            try:
+                reg.detect(b"jpeg", 0.25, reg.resolve_classes(["glove"]))
+            except BaseException as err:  # noqa: BLE001 - reported below
+                errors.append(err)
+
+        worker = threading.Thread(target=slow, daemon=True)
+        worker.start()
+        self.assertTrue(entered.wait(10), "the blocking session never ran")
+
+        # `small_object` needs 400 MiB and only `ppe`'s 400 MiB is reclaimable,
+        # but `ppe` is in flight — so the request is REFUSED rather than
+        # evicting a session a running request still holds a reference to.
+        self.tick()
+        with self.assertRaises(DetectorNotReady):
+            reg.detect(b"jpeg", 0.25, reg.resolve_classes(["rodent"]))
+
+        release.set()
+        worker.join(10)
+        self.assertEqual(errors, [])
+        self.assertIn("ppe", reg.snapshot()["resident_models"])
+
+        # Once it is no longer in flight, the same request succeeds.
+        self.tick()
+        reg.detect(b"jpeg", 0.25, reg.resolve_classes(["rodent"]))
+        self.assertIn("small_object", reg.snapshot()["resident_models"])
+
+
+class TestTheResidencyPolicyRunsOnABareInterpreter(unittest.TestCase):
+    """The strongest form of "these tests run on every CI runner": they CAN.
+
+    `registry.py` reaches a model only through an injected factory, exactly as
+    `server.py` does, so importing the whole residency policy pulls in no ONNX
+    runtime, no numpy and no Pillow. That is what lets eviction, routing and
+    every refusal be exercised on a runner where the ~128 MiB artifact is absent
+    — which is all of them, since it is OTA'd and not committed.
+
+    Verified against a positive control on 2026-08-24, both ways. The same probe
+    against `trillboards_detector.loader` — which DOES need a runtime — reports
+    `['onnxruntime', 'numpy', 'PIL', 'trillboards_detector.session',
+    'trillboards_detector.loader']` on an interpreter that has them, and on a
+    bare one it does not even import (`ModuleNotFoundError: onnxruntime`, which
+    is the non-zero exit this test's returncode assertion catches). The same
+    probe against `registry` on the interpreter WITH the runtime installed
+    reports `[]`, so the emptiness is a property of the module and not of the
+    environment. A check that has never been shown to fail is not a check.
+    """
+
+    def test_importing_the_residency_policy_pulls_in_no_inference_runtime(self):
+        import os
+        import pathlib
+        import subprocess
+        import sys
+
+        probe = (
+            "import sys; import trillboards_detector.registry as r; "
+            "leaked = [m for m in ('onnxruntime','numpy','PIL','trillboards_detector.session',"
+            "'trillboards_detector.loader') if m in sys.modules]; "
+            "print(','.join(leaked))"
+        )
+        package_root = pathlib.Path(__file__).resolve().parents[1]
+        env = dict(os.environ)
+        env["PYTHONPATH"] = os.pathsep.join(
+            [str(package_root)] + ([env["PYTHONPATH"]] if env.get("PYTHONPATH") else []),
+        )
+        out = subprocess.run(
+            [sys.executable, "-c", probe], capture_output=True, text=True, timeout=60, env=env
+        )
+        self.assertEqual(out.returncode, 0, out.stderr)
+        self.assertEqual(
+            out.stdout.strip(),
+            "",
+            "registry.py imported an inference dependency — the residency policy must reach a "
+            "model only through the injected factory, or eviction and routing stop being "
+            "testable on a runner with no artifact",
+        )
+
+
+class TestTheShippedCatalogue(unittest.TestCase):
+    """The one committed vocabulary, checked against the shipped artifact."""
+
+    def test_rfdetr_medium_still_declares_the_91_wide_coco_axis(self):
+        self.assertEqual(RFDETR_MEDIUM.logit_slots, 91)
+        self.assertEqual(dict(RFDETR_MEDIUM.slot_names), dict(COCO91_CLASS_NAMES))
+
+    def test_its_committed_ram_cost_is_the_measured_632_mb(self):
+        """`cctv-detector-tier.md` §6, measured on the shipped 135,146,350-byte
+        fp32 export. A bump is a re-measurement, not a number edit."""
+        self.assertEqual(RFDETR_MEDIUM.approx_ram_bytes, 632 * MB)
+
+    def test_a_vocabulary_naming_a_slot_outside_its_axis_is_refused(self):
+        with self.assertRaisesRegex(ValueError, "outside the declared"):
+            ModelVocabulary("bad", {5: "person"}, logit_slots=3, approx_ram_bytes=1)
+
+    def test_a_vocabulary_with_a_non_canonical_class_name_is_refused(self):
+        """`cell_phone` would be emitted on the wire while the filter matched
+        `cell phone` — a class that silently matches nothing."""
+        with self.assertRaisesRegex(ValueError, "not canonical"):
+            ModelVocabulary("bad", {0: "cell_phone"}, logit_slots=1, approx_ram_bytes=1)
+
+    def test_two_slots_sharing_a_name_is_refused(self):
+        with self.assertRaisesRegex(ValueError, "ambiguous"):
+            ModelVocabulary("bad", {0: "person", 1: "person"}, logit_slots=2, approx_ram_bytes=1)
+
+
+if __name__ == "__main__":
+    unittest.main()