@trillboards/edge-sdk 0.2.89 → 0.2.92

package/deploy/detector/tests/test_box_units.py

@@ -0,0 +1,119 @@
+"""A coordinate space is MEASURED or REFUSED. It is never inferred from silence.
+
+`session.py` takes the layout and the box units from the artifact's DECLARED
+variant contract and never re-derives them from the tensor — that is deliberate,
+because `[1, 300, 6]` and `[1, 6, 8400]` are both rank-3 with a 6 in them and a
+reader that decides from shape alone gets one of them backwards with no
+exception and a plausible table. The whole weight of that design sits on the
+declaration being true.
+
+`classify_box_units` is where the declaration is made, from one forward pass.
+Its refusal band exists because the wrong pick is silent: LiteRT boxes in 0..1
+and ONNX boxes in pixels agree on output shape, dtype, class count and every
+score, and differ only by a factor of imgsz on four channels.
+
+The hole these tests close: the guard was `box_abs_max is None`, so a
+`box_abs_max` of exactly `0.0` fell through to `ratio = 0.0`, landed under
+BOX_UNITS_NORMALIZED_RATIO_MAX, and returned a CONFIDENT `normalized` with
+`scale_to_pixels=640` from zero observations. That is not hypothetical: a model
+whose classification head is dead still emits box rows — `forklift_akdve_11n`
+has healthy boxes (2.93-636 px) and a max class score of 0.0063 — so nothing is
+admitted at threshold and `box_abs_max` never moves off its seed. The dead
+artifact then published a coordinate-space claim no frame supports.
+
+STDLIB ONLY, and that is why `box_units.py` is a separate module: the
+`detector-service` CI lane runs `python3 -m unittest discover` with no pip
+install, and `run_candidate.py` imports onnxruntime at module scope, so a test
+importing it would error the whole lane during discovery rather than skip.
+"""
+
+from __future__ import annotations
+
+import pathlib
+import sys
+import unittest
+
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent / "bench"))
+
+from box_units import (  # noqa: E402
+    BOX_UNITS_NORMALIZED_RATIO_MAX,
+    BOX_UNITS_PIXEL_RATIO_MIN,
+    classify_box_units,
+)
+
+IMGSZ = 640
+
+
+class ZeroEvidenceIsRefused(unittest.TestCase):
+    def test_exactly_zero_refuses(self):
+        """The seed value must not read as a measurement."""
+        r = classify_box_units(0.0, IMGSZ)
+        self.assertIsNone(r["units"], "0.0 observed box extent was classified as a unit system")
+        self.assertIsNone(r["scale_to_pixels"])
+        self.assertIn("unmeasured", r["refusal"])
+
+    def test_negative_refuses(self):
+        """A negative max is impossible from `abs()`, so it means a bug upstream."""
+        self.assertIsNone(classify_box_units(-1.0, IMGSZ)["units"])
+
+    def test_none_still_refuses(self):
+        r = classify_box_units(None, IMGSZ)
+        self.assertIsNone(r["units"])
+        self.assertIn("unmeasured", r["refusal"])
+
+    def test_zero_imgsz_refuses(self):
+        self.assertIsNone(classify_box_units(639.9, 0)["units"])
+
+    def test_the_refusal_is_reachable_at_all(self):
+        """Guards the shape of the bug, not just this instance.
+
+        The refusal string named this exact case and could not be reached. A
+        message describing a state the code cannot produce is not a safeguard.
+        """
+        reasons = {
+            classify_box_units(v, IMGSZ)["refusal"]
+            for v in (None, 0.0, -0.0, -1.0)
+        }
+        self.assertEqual(len(reasons), 1, "every zero-evidence input must give the same reason")
+        self.assertTrue(all(r for r in reasons))
+
+
+class RealMeasurementsStillClassify(unittest.TestCase):
+    """The fix must not widen the refusal into the measured bands."""
+
+    def test_a_normalised_head_is_still_normalised(self):
+        # 1/640 = 0.0016 — a normalised head's ratio, from the runbook.
+        r = classify_box_units(1.0, IMGSZ)
+        self.assertEqual(r["units"], "normalized")
+        self.assertEqual(r["scale_to_pixels"], float(IMGSZ))
+        self.assertIsNone(r["refusal"])
+
+    def test_smallest_credible_normalised_value_survives(self):
+        """The tightest case the fix could have swallowed.
+
+        A normalised box of 1e-6 of the frame is absurd but non-zero, and the
+        distinction the fix draws is between zero and non-zero, not between
+        small and large.
+        """
+        r = classify_box_units(1e-6, IMGSZ)
+        self.assertEqual(r["units"], "normalized")
+
+    def test_a_pixel_head_is_still_pixels(self):
+        r = classify_box_units(639.29, IMGSZ)   # the shipped rfdetr_medium score card
+        self.assertEqual(r["units"], "pixels")
+        self.assertEqual(r["scale_to_pixels"], 1.0)
+
+    def test_the_dead_zone_still_refuses_with_its_ratio(self):
+        mid = (BOX_UNITS_NORMALIZED_RATIO_MAX + BOX_UNITS_PIXEL_RATIO_MIN) / 2
+        r = classify_box_units(mid * IMGSZ, IMGSZ)
+        self.assertIsNone(r["units"])
+        self.assertAlmostEqual(r["ratio"], mid, places=6)
+        self.assertIn("falls between", r["refusal"])
+
+    def test_band_edges_are_inclusive_as_documented(self):
+        self.assertEqual(classify_box_units(BOX_UNITS_PIXEL_RATIO_MIN * IMGSZ, IMGSZ)["units"], "pixels")
+        self.assertEqual(classify_box_units(BOX_UNITS_NORMALIZED_RATIO_MAX * IMGSZ, IMGSZ)["units"], "normalized")
+
+
+if __name__ == "__main__":
+    unittest.main()

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()