@trillboards/edge-sdk 0.2.80 → 0.2.82

package/deploy/detector/tests/test_server.py

@@ -23,7 +23,8 @@ import urllib.error
 import urllib.request
 from dataclasses import dataclass
 
-from trillboards_detector.errors import DetectorNotReady
+from trillboards_detector.errors import DetectorNotReady, UnknownClasses
+from trillboards_detector.labels import RFDETR_MEDIUM, ClassIndex, ModelVocabulary
 from trillboards_detector.server import DetectorServer, MAX_BODY_BYTES
 
 JPEG = bytes([0xFF, 0xD8, 0xFF, 0xE0, 0x00, 0x10, 0x4A, 0x46])
@@ -40,27 +41,57 @@ class FakeDetection:
 
 
 class FakeBatch:
-    def __init__(self, detections, inference_ms=63.4):
+    def __init__(self, detections, inference_ms=63.4, models=("rfdetr_medium",)):
         self.detections = detections
         self.inference_ms = inference_ms
         self.degenerate_dropped = 0
         self.unnamed_class_dropped = 0
+        #: WHICH MODEL(S) ANSWERED. On a single-model box this is one name and
+        #: the emitted payload is byte-identical to what it was before the
+        #: library existed; the wire's `model` field is now derived from it
+        #: rather than from a loader-wide constant, because the answering set is
+        #: a property of the REQUEST once several models are resident.
+        self.models = list(models)
 
 
 class FakeLoader:
-    """Everything `server.py` is allowed to know about the model."""
+    """Everything `server.py` is allowed to know about the models.
+
+    The class index is the REAL one over the REAL shipped vocabulary — only the
+    session is faked. Canonicalisation and the unknown-class refusal are the
+    behaviour under test here, so stubbing them would test the stub.
+    """
 
     model_name = "rfdetr_medium"
 
-    def __init__(self, batch=None, state="ready", raises=None):
+    def __init__(self, batch=None, state="ready", raises=None, vocabularies=(RFDETR_MEDIUM,)):
         self._batch = batch if batch is not None else FakeBatch([])
         self.state = state
         self._raises = raises
         self.calls: list[tuple] = []
+        self._index = ClassIndex(list(vocabularies))
+        self.resolve_calls: list[list[str]] = []
 
     def info(self):
         return {"state": self.state, "model": self.model_name, "model_path": "/stub"}
 
+    def class_index(self):
+        return self._index
+
+    def resolve_classes(self, requested):
+        self.resolve_calls.append(list(requested))
+        canonical, unknown = self._index.resolve(requested)
+        if unknown:
+            raise UnknownClasses(
+                unknown,
+                self._index.class_names,
+                f"requested classes not in this box's vocabulary: {unknown}. "
+                f"Known classes: {sorted(self._index.class_names)}",
+            )
+        if not canonical:
+            raise UnknownClasses([], self._index.class_names, "`classes` resolved to nothing requestable")
+        return canonical
+
     def detect(self, jpeg, min_confidence, wanted):
         self.calls.append((jpeg, min_confidence, wanted))
         if self._raises is not None:
@@ -180,6 +211,99 @@ class TestHealth(ServerCase):
         self.assertEqual(status, 405)
 
 
+class TestHealthReportsResidency(ServerCase):
+    """`/health` must say WHICH models are resident, and still load nothing.
+
+    `sensing-model-library.md` §3 turns the loader into a name -> session map,
+    so "is the detector up" stops being one word. The top-level `state` still
+    describes the pinned general gate — every existing reader parses it, and
+    `LocalDetectorClient.isHealthy()` turns anything but 2xx into "send the
+    frame to the VLM" — and the per-model detail is additive.
+    """
+
+    def test_health_passes_the_residency_report_through_untouched(self):
+        class ResidencyLoader(FakeLoader):
+            def info(self):
+                return {
+                    "state": "ready",
+                    "model": "rfdetr_medium",
+                    "model_path": "/stub",
+                    "models": {
+                        "rfdetr_medium": {"state": "ready", "resident": True, "pinned": True},
+                        "ppe": {"state": "idle", "resident": False, "pinned": False},
+                    },
+                    "resident_models": ["rfdetr_medium"],
+                    "ram_budget_bytes": 1610612736,
+                    "ram_resident_bytes": 662700032,
+                }
+
+        loader = ResidencyLoader()
+        url = self.serve(loader)
+        status, body = self.request(f"{url}/health")
+        self.assertEqual(status, 200)
+        self.assertEqual(body["resident_models"], ["rfdetr_medium"])
+        self.assertEqual(body["models"]["ppe"]["state"], "idle")
+        self.assertEqual(body["ram_budget_bytes"], 1610612736)
+        # THE ASSERTION THAT MATTERS, restated for the multi-model payload: a
+        # bigger report must not have become a probe.
+        self.assertEqual(loader.calls, [])
+        self.assertEqual(loader.resolve_calls, [])
+
+
+class TestTheAnsweringSetIsReported(ServerCase):
+    """§3: "The response's `model` field reports the set that answered." """
+
+    def test_two_models_are_joined_into_the_one_model_string(self):
+        """`LocalDetectorClient` types `model` as `string | null` and never
+        branches on it (`model: typeof parsed?.model === 'string' && parsed.model
+        ? parsed.model : null`), so a joined string is contract-safe — checked
+        against the client, not assumed."""
+        batch = FakeBatch(
+            [FakeDetection("person", 0.9, 1, 1, 5, 5), FakeDetection("glove", 0.8, 2, 2, 4, 4)],
+            models=("rfdetr_medium", "ppe"),
+        )
+        url = self.serve(FakeLoader(batch))
+        status, body = self.detect(url)
+        self.assertEqual(status, 200)
+        self.assertEqual(body["model"], "rfdetr_medium+ppe")
+        self.assertEqual([d["label"] for d in body["detections"]], ["person", "glove"])
+
+    def test_one_model_still_emits_exactly_the_payload_that_shipped(self):
+        batch = FakeBatch([FakeDetection("person", 0.91, 10.0, 20.0, 30.0, 40.0)])
+        url = self.serve(FakeLoader(batch))
+        _, body = self.detect(url)
+        self.assertEqual(body["model"], "rfdetr_medium")
+
+    def test_an_unattributed_batch_is_refused_not_emitted(self):
+        """A result naming no model is a detection nobody can attribute when a
+        specialist later turns out to be wrong. `model` would serialise as `""`,
+        which the client reads as null — plausible, and permanently lossy. 500,
+        a status that cannot be mistaken for a quiet venue."""
+        batch = FakeBatch([FakeDetection("person", 0.9, 1, 1, 5, 5)], models=())
+        url = self.serve(FakeLoader(batch))
+        status, body = self.detect(url)
+        self.assertEqual(status, 500)
+        self.assertNotIn("detections", body)
+
+
+class TestABudgetRefusalIsNotAnEmptyFrame(ServerCase):
+    """A set that will not fit the RAM budget is 503, never a thinner answer."""
+
+    def test_a_portfolio_refusal_reaches_the_client_as_down(self):
+        loader = FakeLoader(
+            state="ready",
+            raises=DetectorNotReady(
+                "this request needs ['ppe', 'small_object'] resident at once, which with "
+                "['rfdetr_medium'] comes to 1500000000 B against a 1073741824 B portfolio budget"
+            ),
+        )
+        url = self.serve(loader)
+        status, body = self.detect(url, classes=["person"])
+        self.assertEqual(status, 503)
+        self.assertNotIn("detections", body)
+        self.assertIn("portfolio budget", body["error"])
+
+
 class TestHealthCannotLoadTheModel(unittest.TestCase):
     """The strongest form of "/health does not load the model": it CANNOT.
 
@@ -317,12 +441,72 @@ class TestClassFilter(ServerCase):
         self.assertEqual(status, 400)
         self.assertIn("shoplifter", body["error"])
 
-    def test_a_partly_unknown_list_proceeds_on_the_known_half(self):
+    def test_a_partly_unknown_list_is_ALSO_a_loud_400(self):
+        """The partial case is the dangerous one, and it used to return 200.
+
+        `["person", "shoplifter"]` proceeded on `person` and dropped
+        `shoplifter` silently, so a profile asking about shoplifting got person
+        counts and no signal that its actual question was discarded. That is the
+        same `yolov8_nano` shape the test above is written against — a capability
+        offered and not delivered — only wearing a 200 instead of a 0%.
+
+        It becomes the COMMON case now that specialist models are EXPRESSIBLE: a
+        PPE profile asks for `glove` and `hairnet` alongside `person`, and on a
+        box holding only the general detector two thirds of the question would
+        vanish.
+
+        Refusing costs the `person` detections too. That is the right trade —
+        which models are resident is decided upstream by the profile push, so a
+        class the box cannot answer is a configuration error, and the client maps
+        400 to `DetectorUnavailableError`, which shadow mode records as
+        `unavailable`. Visible beats quieter.
+
+        THE REFUSAL ITSELF MOVED to `registry.resolve_classes`, because which
+        classes exist is now a property of the models on this box rather than a
+        constant. What this case pins is the half the WIRE owns: an
+        `UnknownClasses` becomes a 400 and the detector is never asked.
+        """
+        loader = FakeLoader()
+        url = self.serve(loader)
+        status, body = self.detect(url, classes=["person", "shoplifter"])
+        self.assertEqual(status, 400)
+        self.assertIn("shoplifter", body["error"])
+        # And the detector was never asked — we refuse before inferring.
+        self.assertEqual(loader.calls, [])
+
+    def test_a_fully_known_list_still_reaches_the_detector(self):
+        """The refusal above must not have made every class request fail."""
         loader = FakeLoader()
         url = self.serve(loader)
-        status, _ = self.detect(url, classes=["person", "shoplifter"])
+        status, _ = self.detect(url, classes=["person", "cell phone"])
         self.assertEqual(status, 200)
-        self.assertEqual(loader.calls[0][2], {"person"})
+        self.assertEqual(loader.calls[0][2], {"person", "cell phone"})
+
+    def test_a_specialists_class_is_requestable_once_its_model_is_in_the_index(self):
+        """THE PIECE THAT MAKES A SPECIALIST EXPRESSIBLE AT THE WIRE.
+
+        Against the hardcoded COCO-91 `KNOWN_CLASS_NAMES` this was a 400 no
+        matter what was on the box, so publishing a PPE model would have changed
+        nothing here. The vocabulary is now the union of what the loader holds.
+        """
+        ppe = ModelVocabulary(
+            model_name="ppe",
+            slot_names={0: "glove", 1: "hairnet"},
+            logit_slots=2,
+            approx_ram_bytes=400 * 1024 * 1024,
+        )
+        loader = FakeLoader(vocabularies=(RFDETR_MEDIUM, ppe))
+        url = self.serve(loader)
+        status, _ = self.detect(url, classes=["person", "Glove"])
+        self.assertEqual(status, 200)
+        self.assertEqual(loader.calls[0][2], {"person", "glove"})
+
+        # And the COCO-only box still refuses it, so the widening is a property
+        # of what is loaded and not of the build.
+        coco_only = FakeLoader()
+        status, body = self.detect(self.serve(coco_only), classes=["person", "Glove"])
+        self.assertEqual(status, 400)
+        self.assertIn("Glove", body["error"])
 
 
 class TestRequestRefusals(ServerCase):

package/deploy/detector/tests/test_session.py

@@ -17,6 +17,7 @@ import unittest
 try:
     import numpy as np
 
+    from trillboards_detector.labels import RFDETR_MEDIUM
     from trillboards_detector.session import (
         ModelContractError,
         _read_graph_spec,
@@ -54,6 +55,7 @@ class TestPostprocess(unittest.TestCase):
             frame_w=640,
             frame_h=480,
             min_confidence=0.25,
+            vocabulary=RFDETR_MEDIUM,
         )
         self.assertEqual(len(batch.detections), 1)
         d = batch.detections[0]
@@ -71,6 +73,7 @@ class TestPostprocess(unittest.TestCase):
             frame_w=100,
             frame_h=100,
             min_confidence=0.25,
+            vocabulary=RFDETR_MEDIUM,
         )
         d = batch.detections[0]
         self.assertEqual((d.x, d.y), (0.0, 0.0))
@@ -84,6 +87,7 @@ class TestPostprocess(unittest.TestCase):
             frame_w=200,
             frame_h=200,
             min_confidence=0.25,
+            vocabulary=RFDETR_MEDIUM,
         )
         self.assertEqual(sorted(d.label for d in batch.detections), ["car", "person"])
 
@@ -92,8 +96,12 @@ class TestPostprocess(unittest.TestCase):
         is OUT, and that has to match: the operating point in the runbook was
         chosen against this comparison, not a >=."""
         args = (_boxes({0: (0.5, 0.5, 0.2, 0.2)}), _logits({(0, 1): 0.5}), 100, 100)
-        self.assertEqual(len(postprocess(*args, min_confidence=0.4).detections), 1)
-        self.assertEqual(len(postprocess(*args, min_confidence=0.5).detections), 0)
+        self.assertEqual(
+            len(postprocess(*args, min_confidence=0.4, vocabulary=RFDETR_MEDIUM).detections), 1
+        )
+        self.assertEqual(
+            len(postprocess(*args, min_confidence=0.5, vocabulary=RFDETR_MEDIUM).detections), 0
+        )
 
     def test_an_unnamed_class_slot_is_dropped_and_counted_never_labelled(self):
         """Eleven of the ninety-one slots are COCO id gaps. Slot 12 is one.
@@ -108,6 +116,7 @@ class TestPostprocess(unittest.TestCase):
             frame_w=100,
             frame_h=100,
             min_confidence=0.25,
+            vocabulary=RFDETR_MEDIUM,
         )
         self.assertEqual(batch.detections, [])
         self.assertEqual(batch.unnamed_class_dropped, 1)
@@ -122,6 +131,7 @@ class TestPostprocess(unittest.TestCase):
             frame_w=100,
             frame_h=100,
             min_confidence=0.25,
+            vocabulary=RFDETR_MEDIUM,
         )
         self.assertEqual(len(batch.detections), 1)
         self.assertEqual(batch.degenerate_dropped, 1)
@@ -134,8 +144,16 @@ class TestPostprocess(unittest.TestCase):
             100,
             0.25,
         )
-        self.assertEqual([d.label for d in postprocess(*args, wanted={"car"}).detections], ["car"])
-        self.assertEqual(len(postprocess(*args, wanted=None).detections), 2)
+        self.assertEqual(
+            [
+                d.label
+                for d in postprocess(*args, wanted={"car"}, vocabulary=RFDETR_MEDIUM).detections
+            ],
+            ["car"],
+        )
+        self.assertEqual(
+            len(postprocess(*args, wanted=None, vocabulary=RFDETR_MEDIUM).detections), 2
+        )
 
     def test_selection_keeps_the_top_300_pairs_before_thresholding(self):
         """`num_select=300` is applied FIRST, exactly as upstream does.
@@ -152,6 +170,7 @@ class TestPostprocess(unittest.TestCase):
             frame_w=100,
             frame_h=100,
             min_confidence=0.25,
+            vocabulary=RFDETR_MEDIUM,
         )
         self.assertEqual(len(batch.detections), 300)
 
@@ -159,7 +178,7 @@ class TestPostprocess(unittest.TestCase):
         rng = np.random.default_rng(7)
         logits = rng.normal(0.0, 40.0, size=(1, 300, 91)).astype(np.float32)
         boxes = np.abs(rng.normal(0.4, 0.2, size=(1, 300, 4))).astype(np.float32)
-        batch = postprocess(boxes, logits, 640, 480, 0.0)
+        batch = postprocess(boxes, logits, 640, 480, 0.0, vocabulary=RFDETR_MEDIUM)
         for d in batch.detections:
             self.assertGreaterEqual(d.confidence, 0.0)
             self.assertLessEqual(d.confidence, 1.0)
@@ -205,7 +224,7 @@ class TestGraphContract(unittest.TestCase):
     GOOD_OUT = [_FakeIo("dets", [1, 300, 4]), _FakeIo("labels", [1, 300, 91])]
 
     def test_accepts_the_shipped_graph(self):
-        spec = _read_graph_spec(_FakeSession(self.GOOD_IN, self.GOOD_OUT))
+        spec = _read_graph_spec(_FakeSession(self.GOOD_IN, self.GOOD_OUT), RFDETR_MEDIUM)
         self.assertEqual((spec.width, spec.height), (576, 576))
         self.assertEqual(spec.num_classes, 91)
         self.assertEqual(spec.input_name, "input")
@@ -213,7 +232,7 @@ class TestGraphContract(unittest.TestCase):
     def test_refuses_a_class_axis_the_label_map_does_not_describe(self):
         out = [_FakeIo("dets", [1, 300, 4]), _FakeIo("labels", [1, 300, 80])]
         with self.assertRaisesRegex(ModelContractError, "80 class slots"):
-            _read_graph_spec(_FakeSession(self.GOOD_IN, out))
+            _read_graph_spec(_FakeSession(self.GOOD_IN, out), RFDETR_MEDIUM)
 
     def test_refuses_a_dynamic_resolution(self):
         """imgsz is one of the two numbers a detector arm is meaningless
@@ -221,12 +240,12 @@ class TestGraphContract(unittest.TestCase):
         the artifact at all."""
         dyn = [_FakeIo("input", [1, 3, "height", "width"])]
         with self.assertRaisesRegex(ModelContractError, "fixed input resolution"):
-            _read_graph_spec(_FakeSession(dyn, self.GOOD_OUT))
+            _read_graph_spec(_FakeSession(dyn, self.GOOD_OUT), RFDETR_MEDIUM)
 
     def test_refuses_unexpected_output_names(self):
         out = [_FakeIo("boxes", [1, 300, 4]), _FakeIo("scores", [1, 300, 91])]
         with self.assertRaisesRegex(ModelContractError, "dets"):
-            _read_graph_spec(_FakeSession(self.GOOD_IN, out))
+            _read_graph_spec(_FakeSession(self.GOOD_IN, out), RFDETR_MEDIUM)
 
     def test_refuses_a_multi_input_graph(self):
         """An open-vocabulary model would carry a text input. Per the runbook
@@ -235,7 +254,7 @@ class TestGraphContract(unittest.TestCase):
         the label map belongs to."""
         two = [_FakeIo("images", [1, 3, 576, 576]), _FakeIo("text", [1, 512])]
         with self.assertRaisesRegex(ModelContractError, "one graph input"):
-            _read_graph_spec(_FakeSession(two, self.GOOD_OUT))
+            _read_graph_spec(_FakeSession(two, self.GOOD_OUT), RFDETR_MEDIUM)
 
 
 if __name__ == "__main__":

package/deploy/detector/trillboards_detector/__init__.py

@@ -5,4 +5,4 @@ Its own uv tool, its own venv, its own OS-supervised loopback service on
 `docs/runbooks/cctv-detector-tier.md` for what it runs and why that model.
 """
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"

package/deploy/detector/trillboards_detector/cli.py

@@ -18,7 +18,7 @@ import threading
 from pathlib import Path
 
 from .loader import DEFAULT_POLL_INTERVAL_S, DetectorLoader
-from .modelpath import DEFAULT_MODEL_NAME, resolve_model_path
+from .modelpath import DEFAULT_MODEL_NAME, resolve_model_path, resolve_ram_budget_mb
 from .server import DEFAULT_HOST, DEFAULT_PORT, serve
 
 LOG = logging.getLogger("trillboards_detector")
@@ -77,6 +77,22 @@ def build_parser() -> argparse.ArgumentParser:
             "wrong and this exists only to reproduce a bench arm."
         ),
     )
+    s.add_argument(
+        "--ram-budget-mb",
+        type=int,
+        default=None,
+        help=(
+            "how much RAM every RESIDENT detector session may occupy TOGETHER, in MiB "
+            "(env TRILLBOARDS_DETECTOR_RAM_BUDGET_MB). THERE IS NO DEFAULT AND THERE "
+            "MUST NOT BE: the allocation authority is server-side "
+            "(sensingProfileService.selectModelForDeviceTier and the model-manifest "
+            "min_ram_mb gate), and a ceiling chosen by this service would be a second "
+            "authority that cannot see the first. Unset, the service still holds the "
+            "model it was told to hold and REFUSES to make any second model resident, "
+            "naming why. Over the ceiling, a request is refused with what did not fit — "
+            "never answered with the half that did."
+        ),
+    )
     s.add_argument("--poll-interval", type=float, default=DEFAULT_POLL_INTERVAL_S)
     s.add_argument("--log-file", default=None, help="also write to this file (Windows has no task stdout)")
     s.add_argument("--verbose", action="store_true")
@@ -92,13 +108,44 @@ def main(argv: "list[str] | None" = None) -> int:
     _configure_logging(args.log_file, args.verbose)
 
     model_path = Path(args.model) if args.model else resolve_model_path(args.model_name)
-    LOG.info("[detector] starting on %s:%s, model %s", args.host, args.port, model_path)
+
+    # PRECEDENCE: flag, then env, then NOTHING. There is deliberately no third
+    # rung — an absent ceiling is a state, not a value to fill in.
+    budget_mb = args.ram_budget_mb if args.ram_budget_mb is not None else resolve_ram_budget_mb()
+    ram_budget_bytes = budget_mb * 1024 * 1024 if budget_mb is not None else None
+
+    # NOT A FATAL EXIT, and that is deliberate. Every one of the three
+    # supervisors restarts this process on a non-zero exit — the crash-loop each
+    # of their definitions carries a ThrottleInterval for — and `loader.py`'s
+    # header already settles the policy for a required input that has not
+    # arrived: START, and report UNHEALTHY with the reason. That is how a missing
+    # OTA'd artifact is handled and a missing ceiling is the same shape. The
+    # refusal is enforced where it belongs, at admission, per request, loudly.
+    if ram_budget_bytes is None:
+        LOG.warning(
+            "[detector] NO RAM CEILING INJECTED — the pinned model %s will still load and "
+            "answer, but NO second model can be made resident and every request that would "
+            "need one is refused with the reason. This service does not pick its own ceiling: "
+            "the allocation authority is server-side. Pass --ram-budget-mb or set "
+            "TRILLBOARDS_DETECTOR_RAM_BUDGET_MB.",
+            args.model_name,
+        )
+
+    LOG.info(
+        "[detector] starting on %s:%s, pinned model %s at %s, ceiling %s",
+        args.host,
+        args.port,
+        args.model_name,
+        model_path,
+        f"{ram_budget_bytes // (1024 * 1024)} MiB (injected)" if ram_budget_bytes else "NOT INJECTED",
+    )
 
     loader = DetectorLoader(
         model_path=model_path,
         model_name=args.model_name,
         intra_op_threads=args.threads,
         poll_interval_s=args.poll_interval,
+        ram_budget_bytes=ram_budget_bytes,
         log=LOG.info,
     )
     loader.start()

package/deploy/detector/trillboards_detector/detections.py

@@ -0,0 +1,98 @@
+"""What one frame's answer looks like, and how two models' answers become one.
+
+STDLIB ONLY, and that is why it is its own module rather than staying in
+`session.py`. A merged result is produced by `registry.py`, which must be
+testable on a bare interpreter — the ~128 MiB ONNX is OTA'd and is absent on
+every CI runner, so any part of this service that can only be exercised with
+onnxruntime present is a part nothing tests. `session.py` re-exports both
+dataclasses, so nothing that imported them from there had to move.
+
+`models` IS PART OF THE RESULT, not decoration. `docs/runbooks/sensing-model-library.md`
+§3: "A request spanning two models runs both and merges. The response's `model`
+field reports the set that answered." A detection whose producer cannot be named
+is a detection that cannot be attributed when a specialist later turns out to be
+wrong, and `cctv-detector-tier.md` §5 rule 2 is a whole scar about exactly that —
+an unattributed class index once scored BUSES as people for an entire eval run
+and the table looked completely plausible.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class Detection:
+    """One wire-shaped detection. Pixel box, canonical label, [0,1] confidence."""
+
+    label: str
+    confidence: float
+    x: float
+    y: float
+    width: float
+    height: float
+
+
+@dataclass
+class DetectionBatch:
+    detections: list[Detection]
+    #: The ORT forward pass alone, in ms — directly comparable to the ~63 ms in
+    #: `docs/runbooks/cctv-detector-tier.md`. Decode and post-processing are
+    #: reported separately (`total_ms`) so a slow JPEG decode cannot hide inside
+    #: a number the runbook will later be checked against.
+    #:
+    #: On a merged batch this is the SUM across the models that answered, which
+    #: is the truth: they run serially on one box, so the wall clock the service
+    #: spent inferring is their sum, not their max. Comparing a two-model figure
+    #: against the single-model ~63 ms is therefore a comparison of different
+    #: things — `models` is on the same object so the reader can see how many.
+    inference_ms: float = 0.0
+    total_ms: float = 0.0
+    #: Boxes that survived the threshold but cover no pixels after clamping to
+    #: the frame. Counted, never silently swallowed — see `session._to_wire`.
+    degenerate_dropped: int = 0
+    #: Detections whose argmax landed on a slot the model's vocabulary does not
+    #: name (for COCO-91, one of the eleven category-id gaps).
+    unnamed_class_dropped: int = 0
+    #: The model(s) that produced this, in the order they ran. Exactly one
+    #: element for a batch off a single session; N for a merged one.
+    models: list[str] = field(default_factory=list)
+
+
+def merge_batches(batches: "list[DetectionBatch]") -> DetectionBatch:
+    """Concatenate several models' answers for ONE frame into one answer.
+
+    ORDER IS CATALOGUE ORDER, NOT SCORE ORDER. The wire contract carries no
+    ordering promise and `LocalDetectorClient` reads the array straight through
+    without sorting, so re-ranking across models here would be inventing a
+    cross-model calibration nobody measured — two detectors' confidences are not
+    on a common scale, and `cctv-detector-tier.md` §2 is the standing warning
+    about comparing models on a number that does not mean the same thing in
+    both.
+
+    THERE IS NO PARTIAL MERGE. Every batch handed here is a model that ran to
+    completion; a model that failed raises long before this, so a short list can
+    never silently become a thinner frame. That is the single collapse this
+    whole component exists to prevent.
+    """
+    if not batches:
+        # Never reachable from `registry.detect`, which refuses an empty plan
+        # with a 503 before inferring. Raising rather than returning an empty
+        # batch keeps it that way: an empty merge is indistinguishable from a
+        # quiet venue, which is the one answer that must never be manufactured.
+        raise ValueError("merge_batches() was given no batches; an empty result must be a 503, not `[]`")
+    if len(batches) == 1:
+        return batches[0]
+
+    merged = DetectionBatch(detections=[])
+    for b in batches:
+        merged.detections.extend(b.detections)
+        merged.inference_ms += b.inference_ms
+        merged.total_ms += b.total_ms
+        merged.degenerate_dropped += b.degenerate_dropped
+        merged.unnamed_class_dropped += b.unnamed_class_dropped
+        merged.models.extend(b.models)
+    return merged
+
+
+__all__ = ["Detection", "DetectionBatch", "merge_batches"]

package/deploy/detector/trillboards_detector/errors.py

@@ -4,6 +4,10 @@ Its own module, with NO third-party imports, so `server.py` stays importable —
 and therefore unit-testable against a stub — on a machine with no onnxruntime,
 no numpy and no Pillow. The wire contract is the load-bearing half of this
 service; it must not need a 128 MiB model or a 50 MB runtime to be tested.
+
+`registry.py` is held to the same rule for the same reason, which is why
+`ModelContractError` lives here rather than in `session.py`: the registry has to
+be able to CLASSIFY a load failure without importing the thing that loads.
 """
 
 
@@ -13,4 +17,38 @@ class DetectorNotReady(RuntimeError):
     The distinction is the entire reason `LocalDetectorClient` exists: a cascade
     that reads "detector down" as "nobody there" suppresses every alert while
     every health surface stays green.
+
+    IT COVERS "WILL NOT FIT" AS WELL AS "IS NOT THERE", deliberately. A request
+    spanning models whose committed RAM cost exceeds the portfolio budget is a
+    request this box cannot answer, and answering it with the half that fits
+    would be a partial result nobody downstream could distinguish from a
+    genuinely emptier frame — `docs/runbooks/sensing-model-library.md` §2:
+    "report what it could not fit rather than silently dropping it."
+    """
+
+
+class ModelContractError(RuntimeError):
+    """The artifact loaded, but it is not a graph this service can label.
+
+    Raised by `session.py` against the model's COMMITTED vocabulary. Named here
+    so `registry.py` can tell "this artifact is the wrong shape" (a permanent
+    fault that will not fix itself on a retry) from "ORT failed to open the
+    file" (which a re-download can fix), without importing onnxruntime.
     """
+
+
+class UnknownClasses(ValueError):
+    """The caller named classes no resident-or-present model can emit.
+
+    A 400, and a LOUD one — never a quieter answer computed from the half we
+    recognised. `docs/runbooks/cctv-detector-tier.md` §5 rule 5 is the scar:
+    `yolov8_nano` was offered to ~97 of 114 profile authors while every device
+    hardcoded it unloadable, and `vehicle_count` sat at ~0% fleet-wide for six
+    months with every surface green.
+    """
+
+    def __init__(self, unknown: "list[str]", known: "frozenset[str]", detail: str = ""):
+        self.unknown = list(unknown)
+        self.known = frozenset(known)
+        self.detail = detail
+        super().__init__(detail or f"unknown classes: {self.unknown}")