@trillboards/edge-sdk 0.2.89 → 0.2.91

package/deploy/detector/tests/test_decode.py

@@ -0,0 +1,559 @@
+"""The two YOLO decodes, against hand-built tensors. No model, no ORT session.
+
+WHY THESE ASSERTIONS AND NOT "IT RETURNS SOMETHING"
+--------------------------------------------------
+Every failure this file is guarding against produces a complete, plausible table:
+
+  * a transposed anchor axis reads box channels as class scores;
+  * a second sigmoid squashes every confidence into 0.5..0.73;
+  * a missing `box_scale_to_pixels` draws every box 640x too small;
+  * suppression skipped or run twice changes the COUNT and nothing else;
+  * `end2end_n_6` decoded as `anchor_4_plus_nc` reads x1,y1,x2,y2,score,cls as
+    four box channels and two classes.
+
+None of them raises, and none of them is visible in a shape or dtype check. So
+each is asserted against a tensor whose right answer is known by construction,
+and `bench/verify_detector_decode.py` is the second control: the same decode
+against `ultralytics`' own NMS on real artifacts.
+
+The whole file is skipped without numpy — the wire contract in `test_server.py`
+needs no third-party package and is the half that must always run. It does NOT
+need onnxruntime, deliberately: `decode.py` imports numpy and nothing else, so
+the arithmetic is exercisable on any runner that can `import numpy`, which is
+strictly more than the 24 cases in `test_session.py` reach.
+"""
+
+from __future__ import annotations
+
+import unittest
+
+try:
+    import numpy as np
+
+    from trillboards_detector.decode import (
+        ANCHOR_4_PLUS_NC,
+        CLASS_OFFSET_STRIDE,
+        DECODABLE_LAYOUTS,
+        END2END_N_6,
+        MAX_DETECTIONS,
+        MAX_NMS_CANDIDATES,
+        NMS_IOU_THRESHOLD,
+        PREPROCESSING_BY_LAYOUT,
+        RFDETR_DETS_LABELS,
+        YOLO_DECODERS,
+        LetterboxGeometry,
+        box_iou_against,
+        decode_anchor_4_plus_nc,
+        decode_end2end_n_6,
+        greedy_nms,
+    )
+    from trillboards_detector.labels import (
+        BOX_UNITS,
+        BOX_UNITS_NORMALIZED,
+        BOX_UNITS_PIXELS,
+        OUTPUT_LAYOUTS,
+        VariantContract,
+    )
+
+    HAVE_NUMPY = True
+except ImportError:  # pragma: no cover - exercised only on a bare interpreter
+    HAVE_NUMPY = False
+
+
+#: An identity mapping: no scaling, no padding, and a "frame" the size of the
+#: model input. Model-input pixels and frame pixels then coincide, so a box's
+#: expected value can be written down directly.
+def _identity(size=640):
+    return LetterboxGeometry(1.0, 0.0, 0.0, size, size)
+
+
+def _anchor(boxes_and_scores, num_classes, anchors=None):
+    """Build `[1, 4+nc, A]` from `[(cx, cy, w, h, {cls: score}), ...]`."""
+    rows = list(boxes_and_scores)
+    total = anchors or len(rows)
+    grid = np.zeros((1, 4 + num_classes, total), dtype=np.float32)
+    for i, (cx, cy, w, h, scores) in enumerate(rows):
+        grid[0, 0, i], grid[0, 1, i], grid[0, 2, i], grid[0, 3, i] = cx, cy, w, h
+        for cls, score in scores.items():
+            grid[0, 4 + cls, i] = score
+    return grid
+
+
+def _end2end(rows):
+    """Build `[1, N, 6]` from `[(x1, y1, x2, y2, score, cls), ...]`."""
+    return np.asarray([list(rows)], dtype=np.float32)
+
+
+def _anchor_decode(raw, geometry, min_confidence, box_scale_to_pixels=1.0):
+    """Decode a hand-built anchor tensor whose class width is right BY
+    CONSTRUCTION, so `expected_classes` is not the subject of the case.
+
+    Reading it off the tensor is exactly what production must never do, which is
+    why it happens HERE and nowhere in `decode.py`: the fixture author knows the
+    width because they wrote it. `TestAnchorClassWidthRefusal` is where a wrong
+    one is passed on purpose.
+    """
+    return decode_anchor_4_plus_nc(
+        raw, geometry, min_confidence,
+        box_scale_to_pixels=box_scale_to_pixels,
+        expected_classes=raw.shape[1] - 4,
+    )
+
+
+def _end2end_decode(raw, geometry, min_confidence, box_scale_to_pixels=1.0, expected_classes=4):
+    return decode_end2end_n_6(
+        raw, geometry, min_confidence,
+        box_scale_to_pixels=box_scale_to_pixels,
+        expected_classes=expected_classes,
+    )
+
+
+@unittest.skipUnless(HAVE_NUMPY, "numpy is not installed")
+class TestDeclaredLayoutSet(unittest.TestCase):
+    """The two halves of one declaration, in two languages, must agree.
+
+    `OUTPUT_LAYOUTS` and `BOX_UNITS` are the box-side copies of the CHECK
+    constraints in
+    `trillboard-api/postgres/migrations/20260825032444_add_variant_coordinate_space.sql`
+    (`model_platform_variants_output_layout_ck`, `..._box_units_ck`). Nothing
+    mechanical can compare a Python frozenset to a SQL CHECK across two
+    languages, so the values are pinned here literally: a value the registry
+    accepts and this build drops publishes a variant nothing can decode, and a
+    value this build accepts and the registry rejects is a model that can never
+    ship. If the SQL set widens, this test is what has to be edited — and the
+    edit is where the new layout's decode gets written.
+    """
+
+    def test_output_layouts_match_the_migrations_check_constraint(self):
+        self.assertEqual(
+            OUTPUT_LAYOUTS,
+            frozenset({"anchor_4_plus_nc", "end2end_n_6", "rfdetr_dets_labels"}),
+        )
+
+    def test_box_units_match_the_migrations_check_constraint(self):
+        self.assertEqual(BOX_UNITS, frozenset({"pixels", "normalized"}))
+
+    def test_every_declarable_layout_has_a_decode(self):
+        """A layout with no decode is a model that loads and answers `[]`."""
+        self.assertEqual(DECODABLE_LAYOUTS, OUTPUT_LAYOUTS)
+        self.assertEqual(frozenset(YOLO_DECODERS), OUTPUT_LAYOUTS - {RFDETR_DETS_LABELS})
+
+    def test_every_layout_names_its_preprocessing(self):
+        self.assertEqual(frozenset(PREPROCESSING_BY_LAYOUT), OUTPUT_LAYOUTS)
+        # The two YOLO heads share one preprocessor and RF-DETR does not share it
+        # with either: that non-sharing is the fact worth pinning.
+        self.assertEqual(
+            PREPROCESSING_BY_LAYOUT[ANCHOR_4_PLUS_NC],
+            PREPROCESSING_BY_LAYOUT[END2END_N_6],
+        )
+        self.assertNotEqual(
+            PREPROCESSING_BY_LAYOUT[RFDETR_DETS_LABELS],
+            PREPROCESSING_BY_LAYOUT[ANCHOR_4_PLUS_NC],
+        )
+
+    def test_the_ultralytics_defaults_are_the_ones_a_score_assumes(self):
+        """`ultralytics/cfg/default.yaml`: iou 0.7, max_det 300, max_wh 7680."""
+        self.assertEqual(NMS_IOU_THRESHOLD, 0.7)
+        self.assertEqual(MAX_DETECTIONS, 300)
+        self.assertEqual(MAX_NMS_CANDIDATES, 30000)
+        self.assertEqual(CLASS_OFFSET_STRIDE, 7680)
+
+
+@unittest.skipUnless(HAVE_NUMPY, "numpy is not installed")
+class TestVariantContract(unittest.TestCase):
+    def test_an_unknown_layout_is_refused_at_declaration(self):
+        with self.assertRaisesRegex(ValueError, "not one of"):
+            VariantContract("yolo_v99_head", BOX_UNITS_PIXELS, 1.0)
+
+    def test_unknown_units_are_refused(self):
+        with self.assertRaisesRegex(ValueError, "box_units"):
+            VariantContract(ANCHOR_4_PLUS_NC, "0..640", 1.0)
+
+    def test_pixels_with_a_scale_that_is_not_one_is_refused(self):
+        """Mirrors `model_platform_variants_box_scale_ck`. A scale of 640 next to
+        `pixels` reads as a declaration and would multiply every box by 640."""
+        with self.assertRaisesRegex(ValueError, "already pixels"):
+            VariantContract(ANCHOR_4_PLUS_NC, BOX_UNITS_PIXELS, 640.0)
+
+    def test_normalized_without_a_scale_is_refused(self):
+        with self.assertRaisesRegex(ValueError, "positive box_scale_to_pixels"):
+            VariantContract(ANCHOR_4_PLUS_NC, BOX_UNITS_NORMALIZED, 0.0)
+
+    def test_normalized_with_a_scale_is_accepted(self):
+        contract = VariantContract(ANCHOR_4_PLUS_NC, BOX_UNITS_NORMALIZED, 640.0)
+        self.assertEqual(contract.box_scale_to_pixels, 640.0)
+
+
+@unittest.skipUnless(HAVE_NUMPY, "numpy is not installed")
+class TestIouAndSuppression(unittest.TestCase):
+    def test_iou_of_identical_boxes_is_one_and_of_disjoint_boxes_is_zero(self):
+        box = np.asarray([0.0, 0.0, 10.0, 10.0], dtype=np.float32)
+        others = np.asarray([[0.0, 0.0, 10.0, 10.0], [20.0, 20.0, 30.0, 30.0]], dtype=np.float32)
+        got = box_iou_against(box, others)
+        self.assertAlmostEqual(float(got[0]), 1.0, places=6)
+        self.assertAlmostEqual(float(got[1]), 0.0, places=6)
+
+    def test_half_overlap_is_one_third(self):
+        """Two 10x10 boxes sharing a 5x10 strip: 50 / (100 + 100 - 50)."""
+        box = np.asarray([0.0, 0.0, 10.0, 10.0], dtype=np.float32)
+        others = np.asarray([[5.0, 0.0, 15.0, 10.0]], dtype=np.float32)
+        self.assertAlmostEqual(float(box_iou_against(box, others)[0]), 1.0 / 3.0, places=6)
+
+    def test_a_zero_area_box_does_not_suppress_a_real_one(self):
+        box = np.asarray([5.0, 5.0, 5.0, 5.0], dtype=np.float32)
+        others = np.asarray([[0.0, 0.0, 10.0, 10.0]], dtype=np.float32)
+        self.assertEqual(float(box_iou_against(box, others)[0]), 0.0)
+
+    def test_nms_keeps_the_best_and_drops_what_overlaps_it(self):
+        boxes = np.asarray(
+            [[0, 0, 10, 10], [1, 1, 11, 11], [50, 50, 60, 60]], dtype=np.float32
+        )
+        scores = np.asarray([0.9, 0.8, 0.7], dtype=np.float32)
+        self.assertEqual(list(greedy_nms(boxes, scores, 0.5)), [0, 2])
+
+    def test_nms_keeps_a_neighbour_below_the_threshold(self):
+        boxes = np.asarray([[0, 0, 10, 10], [5, 0, 15, 10]], dtype=np.float32)
+        scores = np.asarray([0.9, 0.8], dtype=np.float32)
+        # IoU is 1/3, under 0.7, so both survive at the shipped threshold.
+        self.assertEqual(list(greedy_nms(boxes, scores, NMS_IOU_THRESHOLD)), [0, 1])
+        self.assertEqual(list(greedy_nms(boxes, scores, 0.3)), [0])
+
+    def test_nms_of_nothing_is_an_empty_index_and_not_an_exception(self):
+        empty = np.zeros((0, 4), dtype=np.float32)
+        self.assertEqual(greedy_nms(empty, np.zeros((0,), dtype=np.float32), 0.7).shape, (0,))
+
+    def test_ties_break_by_first_index_and_not_by_reversal(self):
+        """`argsort(scores)[::-1]` reverses ties too, so the survivor flips."""
+        boxes = np.asarray([[0, 0, 10, 10], [0, 0, 10, 10]], dtype=np.float32)
+        scores = np.asarray([0.5, 0.5], dtype=np.float32)
+        self.assertEqual(list(greedy_nms(boxes, scores, 0.7)), [0])
+
+
+@unittest.skipUnless(HAVE_NUMPY, "numpy is not installed")
+class TestAnchorDecode(unittest.TestCase):
+    def test_cxcywh_becomes_frame_pixels(self):
+        raw = _anchor([(100.0, 200.0, 40.0, 60.0, {1: 0.9})], num_classes=3)
+        scores, classes, x0, y0, x1, y1 = _anchor_decode(
+            raw, _identity(), 0.25, 1.0
+        )
+        self.assertEqual(len(scores), 1)
+        self.assertAlmostEqual(float(scores[0]), 0.9, places=6)
+        self.assertEqual(int(classes[0]), 1)
+        self.assertAlmostEqual(float(x0[0]), 80.0, places=4)
+        self.assertAlmostEqual(float(y0[0]), 170.0, places=4)
+        self.assertAlmostEqual(float(x1[0]), 120.0, places=4)
+        self.assertAlmostEqual(float(y1[0]), 230.0, places=4)
+
+    def test_scores_are_taken_as_given_and_never_sigmoided_again(self):
+        """An Ultralytics detect head applies it inside the graph. A second one
+        turns 0.9 into 0.711 and leaves a table that still looks like
+        confidences."""
+        raw = _anchor([(10.0, 10.0, 4.0, 4.0, {0: 0.9})], num_classes=1)
+        scores, *_ = _anchor_decode(raw, _identity(), 0.25)
+        self.assertAlmostEqual(float(scores[0]), 0.9, places=6)
+
+    def test_the_best_class_wins_and_the_others_are_not_emitted(self):
+        """`multi_label` is False in Ultralytics' predict path, so one anchor
+        yields at most one detection however many classes clear the floor."""
+        raw = _anchor([(10.0, 10.0, 4.0, 4.0, {0: 0.4, 2: 0.8, 3: 0.6})], num_classes=4)
+        scores, classes, *_ = _anchor_decode(
+            raw, _identity(), 0.25, 1.0
+        )
+        self.assertEqual(len(scores), 1)
+        self.assertEqual(int(classes[0]), 2)
+
+    def test_normalized_boxes_are_scaled_to_pixels_by_the_declared_factor(self):
+        """THE 640x TRAP. Same tensor, same shape, same dtype, same scores."""
+        raw = _anchor([(0.5, 0.5, 0.1, 0.2, {0: 0.9})], num_classes=1)
+        _, _, x0, y0, x1, y1 = _anchor_decode(
+            raw, _identity(), 0.25, 640.0
+        )
+        self.assertAlmostEqual(float(x0[0]), 288.0, places=3)
+        self.assertAlmostEqual(float(y0[0]), 256.0, places=3)
+        self.assertAlmostEqual(float(x1[0]), 352.0, places=3)
+        self.assertAlmostEqual(float(y1[0]), 384.0, places=3)
+
+    def test_the_same_tensor_read_as_pixels_is_640x_too_small_and_never_raises(self):
+        """The negative control for the trap above, asserted rather than trusted:
+        a box 64 px wide becomes 0.1 px wide, with an identical score and class.
+        Nothing about the result says it is wrong, which is why the units are a
+        declaration and not an inference."""
+        raw = _anchor([(0.5, 0.5, 0.1, 0.2, {0: 0.9})], num_classes=1)
+        scores, classes, x0, _, x1, _ = _anchor_decode(
+            raw, _identity(), 0.25, 1.0
+        )
+        self.assertAlmostEqual(float(scores[0]), 0.9, places=6)
+        self.assertEqual(int(classes[0]), 0)
+        self.assertAlmostEqual(float(x1[0]) - float(x0[0]), 0.1, places=5)
+
+    def test_overlapping_boxes_of_one_class_are_suppressed(self):
+        raw = _anchor(
+            [
+                (100.0, 100.0, 50.0, 50.0, {0: 0.9}),
+                (102.0, 102.0, 50.0, 50.0, {0: 0.8}),
+                (400.0, 400.0, 50.0, 50.0, {0: 0.7}),
+            ],
+            num_classes=1,
+        )
+        scores, *_ = _anchor_decode(raw, _identity(), 0.25)
+        self.assertEqual([round(float(s), 3) for s in scores], [0.9, 0.7])
+
+    def test_suppression_never_crosses_classes(self):
+        """`agnostic=False`: two labels on the same object must both survive, or
+        a PPE model's `helmet` silently deletes its own `person`."""
+        raw = _anchor(
+            [
+                (100.0, 100.0, 50.0, 50.0, {0: 0.9}),
+                (100.0, 100.0, 50.0, 50.0, {1: 0.8}),
+            ],
+            num_classes=2,
+        )
+        scores, classes, *_ = _anchor_decode(
+            raw, _identity(), 0.25, 1.0
+        )
+        self.assertEqual(sorted(int(c) for c in classes), [0, 1])
+        self.assertEqual(len(scores), 2)
+
+    def test_the_confidence_floor_is_strict(self):
+        raw = _anchor([(10.0, 10.0, 4.0, 4.0, {0: 0.25})], num_classes=1)
+        scores, *_ = _anchor_decode(raw, _identity(), 0.25)
+        self.assertEqual(len(scores), 0)
+
+    def test_an_empty_frame_returns_empty_arrays_of_the_right_dtype(self):
+        raw = _anchor([(10.0, 10.0, 4.0, 4.0, {0: 0.01})], num_classes=1)
+        scores, classes, x0, y0, x1, y1 = _anchor_decode(
+            raw, _identity(), 0.25, 1.0
+        )
+        for arr in (scores, x0, y0, x1, y1):
+            self.assertEqual(arr.shape, (0,))
+        self.assertEqual(classes.dtype, np.int64)
+
+    def test_more_than_max_detections_are_truncated(self):
+        rows = [
+            (float(20 * i + 10), 10.0, 4.0, 4.0, {0: 0.9})
+            for i in range(MAX_DETECTIONS + 25)
+        ]
+        raw = _anchor(rows, num_classes=1)
+        scores, *_ = _anchor_decode(raw, _identity(), 0.25)
+        self.assertEqual(len(scores), MAX_DETECTIONS)
+
+    def test_letterbox_padding_is_removed_and_the_gain_undone(self):
+        """A 1200x900 frame at 640: gain 0.5333, 80 px of padding top and bottom.
+        A box centred in the letterboxed square is centred in the frame."""
+        gain = 640.0 / 1200.0
+        geometry = LetterboxGeometry(gain, 0.0, 80.0, 1200, 900)
+        raw = _anchor([(320.0, 320.0, 64.0, 64.0, {0: 0.9})], num_classes=1)
+        _, _, x0, y0, x1, y1 = _anchor_decode(
+            raw, geometry, 0.25, box_scale_to_pixels=1.0
+        )
+        self.assertAlmostEqual((float(x0[0]) + float(x1[0])) / 2.0, 600.0, places=3)
+        self.assertAlmostEqual((float(y0[0]) + float(y1[0])) / 2.0, 450.0, places=3)
+
+    def test_a_box_running_off_the_frame_is_clipped_to_it(self):
+        raw = _anchor([(0.0, 0.0, 100.0, 100.0, {0: 0.9})], num_classes=1)
+        _, _, x0, y0, x1, y1 = _anchor_decode(
+            raw, _identity(100), 0.25, 1.0
+        )
+        self.assertEqual((float(x0[0]), float(y0[0])), (0.0, 0.0))
+        self.assertAlmostEqual(float(x1[0]), 50.0, places=4)
+
+    def test_a_tensor_with_no_class_channels_is_refused(self):
+        with self.assertRaisesRegex(ValueError, "at least one class"):
+            decode_anchor_4_plus_nc(
+                np.zeros((1, 4, 10), dtype=np.float32), _identity(), 0.25,
+                box_scale_to_pixels=1.0, expected_classes=1,
+            )
+
+    def test_a_rank_two_tensor_is_refused_rather_than_reshaped(self):
+        with self.assertRaisesRegex(ValueError, ANCHOR_4_PLUS_NC):
+            decode_anchor_4_plus_nc(
+                np.zeros((5, 8400), dtype=np.float32), _identity(), 0.25,
+                box_scale_to_pixels=1.0, expected_classes=1,
+            )
+
+
+@unittest.skipUnless(HAVE_NUMPY, "numpy is not installed")
+class TestEnd2EndDecode(unittest.TestCase):
+    def test_rows_are_x1y1x2y2_score_cls_in_that_order(self):
+        raw = _end2end([(10.0, 20.0, 30.0, 40.0, 0.9, 2.0)])
+        scores, classes, x0, y0, x1, y1 = _end2end_decode(
+            raw, _identity(), 0.25, box_scale_to_pixels=1.0
+        )
+        self.assertAlmostEqual(float(scores[0]), 0.9, places=6)
+        self.assertEqual(int(classes[0]), 2)
+        self.assertEqual(
+            (float(x0[0]), float(y0[0]), float(x1[0]), float(y1[0])), (10.0, 20.0, 30.0, 40.0)
+        )
+
+    def test_already_suppressed_rows_are_not_suppressed_again(self):
+        """Two heavily overlapping rows are the model's own answer here. Running
+        NMS would delete one and produce a count nothing upstream ever measured."""
+        raw = _end2end(
+            [
+                (100.0, 100.0, 150.0, 150.0, 0.9, 0.0),
+                (101.0, 101.0, 151.0, 151.0, 0.8, 0.0),
+            ]
+        )
+        scores, *_ = _end2end_decode(raw, _identity(), 0.25)
+        self.assertEqual(len(scores), 2)
+
+    def test_the_row_order_is_preserved_and_not_re_ranked(self):
+        raw = _end2end(
+            [
+                (0.0, 0.0, 10.0, 10.0, 0.9, 0.0),
+                (20.0, 20.0, 30.0, 30.0, 0.4, 1.0),
+                (40.0, 40.0, 50.0, 50.0, 0.6, 2.0),
+            ]
+        )
+        scores, classes, *_ = _end2end_decode(raw, _identity(), 0.25)
+        self.assertEqual([int(c) for c in classes], [0, 1, 2])
+        self.assertEqual([round(float(s), 3) for s in scores], [0.9, 0.4, 0.6])
+
+    def test_the_confidence_floor_is_strict(self):
+        raw = _end2end([(0.0, 0.0, 10.0, 10.0, 0.25, 0.0)])
+        scores, *_ = _end2end_decode(raw, _identity(), 0.25)
+        self.assertEqual(len(scores), 0)
+
+    def test_normalized_rows_are_scaled_by_the_declared_factor(self):
+        raw = _end2end([(0.25, 0.25, 0.5, 0.5, 0.9, 0.0)])
+        _, _, x0, y0, x1, y1 = _end2end_decode(
+            raw, _identity(), 0.25, box_scale_to_pixels=640.0
+        )
+        self.assertEqual(
+            (float(x0[0]), float(y0[0]), float(x1[0]), float(y1[0])), (160.0, 160.0, 320.0, 320.0)
+        )
+
+    def test_a_padded_tail_of_zero_rows_is_dropped_by_the_floor(self):
+        """These graphs emit a fixed 300 rows and pad with zeros; a zero row has
+        score 0 and class 0, and would otherwise be a `person` at the origin."""
+        rows = [(10.0, 10.0, 20.0, 20.0, 0.9, 1.0)] + [(0.0, 0.0, 0.0, 0.0, 0.0, 0.0)] * 299
+        scores, classes, *_ = _end2end_decode(
+            _end2end(rows), _identity(), 0.25, box_scale_to_pixels=1.0
+        )
+        self.assertEqual(len(scores), 1)
+        self.assertEqual(int(classes[0]), 1)
+
+    def test_a_tensor_whose_last_axis_is_not_six_is_refused(self):
+        with self.assertRaisesRegex(ValueError, END2END_N_6):
+            _end2end_decode(np.zeros((1, 300, 5), dtype=np.float32), _identity(), 0.25)
+
+    def test_an_anchor_tensor_handed_to_this_decode_is_refused_not_misread(self):
+        """`[1, 6, 8400]` and `[1, 300, 6]` are both rank-3 with a 6 in them.
+        This is the confusion the declared layout exists to make impossible, and
+        the refusal is what keeps a mis-declaration loud instead of plausible."""
+        with self.assertRaisesRegex(ValueError, END2END_N_6):
+            _end2end_decode(np.zeros((1, 6, 8400), dtype=np.float32), _identity(), 0.25)
+
+
+@unittest.skipUnless(HAVE_NUMPY, "numpy is not installed")
+class TestCrossLayoutRefusal(unittest.TestCase):
+    """Each decode handed the OTHER layout's tensor must refuse, both ways.
+
+    This is the failure the declared layout exists to prevent, checked at the
+    tensor rather than at the graph. `_read_graph_spec` refuses a mis-declared
+    artifact at LOAD from the shape the graph DECLARES; this refuses it from the
+    array ORT actually returned, which is a different claim the moment an axis is
+    dynamic. Neither check is redundant and neither alone is the whole guard.
+
+    A decode that "works" on the wrong layout is the shape that matters: there is
+    no exception, no NaN, no wrong dtype and no out-of-range confidence to notice
+    — one measurement of it produced a confident `cls_maxabs` of 632 from a box
+    coordinate read as a class score.
+    """
+
+    def test_an_end2end_tensor_sent_to_the_anchor_decode_is_refused(self):
+        """`[1, 300, 6]` arrives here as 300 - 4 = 296 "classes" over 6
+        "anchors" and decodes without raising into a meaningless table."""
+        raw = _end2end([(0.0, 0.0, 10.0, 10.0, 0.9, 1.0)] * 300)
+        with self.assertRaisesRegex(ValueError, r"296 class channels but this model's"):
+            decode_anchor_4_plus_nc(
+                raw, _identity(), 0.25, box_scale_to_pixels=1.0, expected_classes=2
+            )
+
+    def test_an_anchor_tensor_sent_to_the_end2end_decode_is_refused(self):
+        """`[1, 6, 8400]` has a 6 in it too — read as rows it would return six
+        detections whose `cls` column is a box coordinate."""
+        with self.assertRaisesRegex(ValueError, END2END_N_6):
+            _end2end_decode(np.zeros((1, 6, 8400), dtype=np.float32), _identity(), 0.25)
+
+    def test_the_anchor_refusal_names_the_other_layout(self):
+        """The message has to point at the fix. A bare shape mismatch sends the
+        reader to the artifact; naming `end2end_n_6` sends them to the row."""
+        raw = _end2end([(0.0, 0.0, 10.0, 10.0, 0.9, 1.0)] * 300)
+        with self.assertRaises(ValueError) as caught:
+            decode_anchor_4_plus_nc(
+                raw, _identity(), 0.25, box_scale_to_pixels=1.0, expected_classes=2
+            )
+        self.assertIn(END2END_N_6, str(caught.exception))
+
+    def test_a_correct_width_is_not_refused(self):
+        """The negative half of the control: the check must not fire on the
+        artifact it is meant to let through."""
+        raw = _anchor([(10.0, 10.0, 4.0, 4.0, {0: 0.9})], num_classes=2)
+        scores, *_ = decode_anchor_4_plus_nc(
+            raw, _identity(), 0.25, box_scale_to_pixels=1.0, expected_classes=2
+        )
+        self.assertEqual(len(scores), 1)
+
+
+@unittest.skipUnless(HAVE_NUMPY, "numpy is not installed")
+class TestNoClampBeforeSuppression(unittest.TestCase):
+    """A real head puts boxes off the frame; clipping early hides a layout error.
+
+    Measured on a committed artifact: box values reach -45.1 px. Clipping to the
+    frame before NMS moves a box's area, moves its IoU with its neighbours, and
+    changes which one survives — so the shipped answer would depend on a step
+    Ultralytics does not take, and an off-frame coordinate that should look wrong
+    would have been made to look sane first.
+    """
+
+    def test_a_box_outside_the_frame_still_participates_in_suppression(self):
+        # Two boxes overlapping at IoU 1.0, both hanging off the left edge. If
+        # either were clipped first they would stop being identical.
+        raw = _anchor(
+            [
+                (-20.0, 100.0, 100.0, 100.0, {0: 0.9}),
+                (-20.0, 100.0, 100.0, 100.0, {0: 0.8}),
+            ],
+            num_classes=1,
+        )
+        scores, _, x0, *_ = _anchor_decode(raw, _identity(), 0.25)
+        self.assertEqual(len(scores), 1)
+        self.assertAlmostEqual(float(scores[0]), 0.9, places=6)
+        # And the survivor IS clamped on the way out — the wire carries pixels of
+        # the submitted frame, and a negative one is not one.
+        self.assertEqual(float(x0[0]), 0.0)
+
+    def test_clipping_first_would_suppress_a_box_that_must_survive(self):
+        """The discriminating case, and it took a second attempt to build one.
+
+        Two boxes hanging off the left edge:
+
+            A  xyxy [-100, 0, 100, 100]   area 20,000
+            B  xyxy [-300, 0, 100, 100]   area 40,000
+
+        UNCLIPPED their IoU is 20,000 / 40,000 = 0.5, under the 0.7 threshold, so
+        both survive — which is what Ultralytics does and therefore what the
+        published number was measured on. CLIPPED to the frame first, both become
+        [0, 0, 100, 100], IoU 1.0, and the second is suppressed. One detection
+        disappears and nothing anywhere reports it.
+
+        The first fixture written for this did NOT discriminate: both boxes
+        clipped to ZERO width, `box_iou_against` scores a zero-area box 0, and
+        the mutant passed. A negative control that survives its own mutant is
+        worth nothing, so the geometry here is chosen for the property rather
+        than for looking off-frame.
+        """
+        raw = _anchor(
+            [
+                (0.0, 50.0, 200.0, 100.0, {0: 0.9}),
+                (-100.0, 50.0, 400.0, 100.0, {0: 0.8}),
+            ],
+            num_classes=1,
+        )
+        scores, *_ = _anchor_decode(raw, _identity(), 0.25)
+        self.assertEqual([round(float(v), 3) for v in scores], [0.9, 0.8])
+
+
+if __name__ == "__main__":
+    unittest.main()

package/deploy/detector/tests/test_loader.py

@@ -16,7 +16,13 @@ from __future__ import annotations
 import unittest
 
 try:
-    from trillboards_detector.labels import RFDETR_MEDIUM, ModelVocabulary
+    from trillboards_detector.labels import (
+        ANCHOR_4_PLUS_NC,
+        BOX_UNITS_PIXELS,
+        RFDETR_MEDIUM,
+        ModelVocabulary,
+        VariantContract,
+    )
     from trillboards_detector.loader import DetectorLoader, build_catalogue
 
     HAVE_RUNTIME = True
@@ -30,6 +36,9 @@ if HAVE_RUNTIME:
         slot_names={0: "glove", 1: "hairnet"},
         logit_slots=2,
         approx_ram_bytes=400 * 1024 * 1024,
+        # A specialist is an Ultralytics export, which is the whole reason the
+        # catalogue can hold one now.
+        onnx_variant=VariantContract(ANCHOR_4_PLUS_NC, BOX_UNITS_PIXELS, 1.0),
     )
 
 

package/deploy/detector/tests/test_registry.py

@@ -25,7 +25,20 @@ 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.labels import (
+    ANCHOR_4_PLUS_NC,
+    BOX_UNITS_PIXELS,
+    COCO91_CLASS_NAMES,
+    RFDETR_DETS_LABELS,
+    RFDETR_MEDIUM,
+    ModelVocabulary,
+    VariantContract,
+)
+
+#: Stand-ins for the two variant rows a catalogue holds today: the shipped
+#: RF-DETR contract and an Ultralytics specialist's.
+DETS_LABELS_ONNX = VariantContract(RFDETR_DETS_LABELS, BOX_UNITS_PIXELS, 1.0)
+ANCHOR_ONNX = VariantContract(ANCHOR_4_PLUS_NC, BOX_UNITS_PIXELS, 1.0)
 from trillboards_detector.registry import (
     STATE_ABSENT,
     STATE_IDLE,
@@ -44,6 +57,7 @@ GENERAL = ModelVocabulary(
     slot_names={1: "person", 3: "car"},
     logit_slots=91,
     approx_ram_bytes=600 * MB,
+    onnx_variant=DETS_LABELS_ONNX,
 )
 
 #: A PPE specialist — the §3 worked example. It ALSO emits `person`, which is
@@ -53,6 +67,7 @@ PPE = ModelVocabulary(
     slot_names={0: "person", 1: "glove", 2: "hairnet"},
     logit_slots=3,
     approx_ram_bytes=400 * MB,
+    onnx_variant=ANCHOR_ONNX,
 )
 
 #: A third specialist, so eviction has something to choose between.
@@ -61,6 +76,7 @@ SMALL_OBJECT = ModelVocabulary(
     slot_names={0: "rodent"},
     logit_slots=1,
     approx_ram_bytes=400 * MB,
+    onnx_variant=ANCHOR_ONNX,
 )
 
 
@@ -558,6 +574,28 @@ class TestDownIsNeverEmpty(RegistryCase):
         self.assertIn("does not match the detector contract", str(caught.exception))
         self.assertEqual(reg.snapshot()["models"]["ppe"]["state"], STATE_UNAVAILABLE)
 
+    def test_an_undecodable_layout_is_a_refusal_and_never_an_empty_frame(self):
+        """DOWN IS NEVER EMPTY, and this is the shape it now arrives in.
+
+        `_read_graph_spec` raises `ModelContractError` when the graph disagrees
+        with the variant's declared `output_layout` — an artifact re-exported
+        end2end under a row still saying `anchor_4_plus_nc`, say. That has to
+        become a 503, because the alternative is a decode that reads the tensor
+        the wrong way and returns a full, plausible, wrong table, or an empty one
+        that nothing downstream can tell from a quiet venue.
+        """
+        self.write_artifact("general")
+        self.write_artifact("ppe")
+        self.factory_raises["ppe"] = ModelContractError(
+            "end2end_n_6 is not (1, N, 6) — x1,y1,x2,y2,score,cls: [1, 6, 8400]"
+        )
+        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("x1,y1,x2,y2,score,cls", 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
@@ -863,17 +901,17 @@ class TestTheShippedCatalogue(unittest.TestCase):
 
     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)
+            ModelVocabulary("bad", {5: "person"}, 3, 1, ANCHOR_ONNX)
 
     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)
+            ModelVocabulary("bad", {0: "cell_phone"}, 1, 1, ANCHOR_ONNX)
 
     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)
+            ModelVocabulary("bad", {0: "person", 1: "person"}, 2, 1, ANCHOR_ONNX)
 
 
 if __name__ == "__main__":