@trillboards/edge-sdk 0.2.92 → 0.2.94

package/deploy/detector/tests/test_onnx_artifact_probe.py

@@ -0,0 +1,618 @@
+"""`scripts/sensing/onnx_artifact_probe.py` — the DECLARED layout, VERIFIED.
+
+WHY THIS SUITE LIVES HERE AND NOT NEXT TO THE SCRIPT
+----------------------------------------------------
+The probe is Python, and the only lane in this repo that executes Python is
+`detector-service`, which discovers `test_*.py` under `deploy/detector`. Putting
+these cases anywhere else would make them the shape the probe itself is written
+against: a check that exists and never runs. `test_session.py`'s
+`TestEveryVocabularyConstructionDeclaresItsVariant` already reaches out of this
+package into `scripts/sensing` for the same reason, and it did so because the
+first version of that guard scanned only `deploy/detector` and passed while the
+probe held a broken `ModelVocabulary` construction.
+
+STDLIB ONLY, so it runs on that lane's bare interpreter — no onnxruntime, no
+numpy, no Pillow, no ~12 MiB artifact. Everything under test here is arithmetic
+over shapes an exporter wrote down, so a fake output descriptor with a `.name`
+and a `.shape` is not a weaker input than a real `NodeArg`; it is the same two
+fields. What it cannot reach — that a graph this accepts also RUNS — is covered
+by the probe's own measurement child, which loads the artifact and infers.
+
+WHAT IS BEING PROTECTED
+-----------------------
+Three failures, none of which raises anything at runtime:
+
+  * a DEFAULT that moved. The probe answers `--artifact` alone exactly as it did
+    before layouts were declarable, which is the only reason `rfdetr_medium`'s
+    published probe result is still reproducible. A new flag that quietly widened
+    that path would republish a different number under the same provenance.
+  * a layout DECLARED that the graph cannot speak. `[1, 300, 6]` and
+    `[1, 6, 8400]` are both rank-3 with a 6 in them, and the wrong one decodes
+    into a confident, meaningless table.
+  * a `4 + nc` check counting the wrong `nc`. Distinct NAMES and LOGIT SLOTS are
+    different numbers on real artifacts in both directions, and using the name
+    count rejects healthy graphs.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import importlib.util
+import io
+import json
+import pathlib
+import sys
+import tempfile
+import unittest
+
+from trillboards_detector import labels as labels_mod
+
+
+def _load_probe():
+    """Import the probe BY PATH, or return None on a checkout that has none.
+
+    `deploy/` ships inside the npm tarball, so on an installed connector
+    `scripts/sensing` is simply absent. The module is loaded rather than asserted
+    for exactly that reason — the same concession `test_session.py` makes about
+    the repo roots it scans.
+    """
+    here = pathlib.Path(__file__).resolve().parent.parent
+    for parent in here.parents:
+        # A git WORKTREE's `.git` is a file, not a directory.
+        if not (parent / ".git").exists():
+            continue
+        candidate = parent / "scripts" / "sensing" / "onnx_artifact_probe.py"
+        if not candidate.is_file():
+            return None
+        spec = importlib.util.spec_from_file_location("onnx_artifact_probe_under_test", candidate)
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+        return module
+    return None
+
+
+PROBE = _load_probe()
+NO_PROBE = "scripts/sensing/onnx_artifact_probe.py is not in this checkout"
+
+
+class Out:
+    """An ORT output descriptor, which is a `.name` and a `.shape` and nothing else.
+
+    A dynamic axis arrives from onnxruntime as a symbolic STRING rather than an
+    int, so several cases here pass one — that is a real artifact property and
+    the probe's branches turn on it.
+    """
+
+    def __init__(self, name: str, shape: "list"):
+        self.name = name
+        self.shape = shape
+
+    def __repr__(self) -> str:  # pragma: no cover - only reached in a failure message
+        return f"Out({self.name!r}, {self.shape!r})"
+
+
+DETS_LABELS_91 = [Out("dets", [1, 300, 4]), Out("labels", [1, 300, 91])]
+#: `ppe_vyra_14cls_v8m.onnx`, measured: 14 classes, so 4 + 14 = 18 channels.
+ANCHOR_14 = [Out("output0", [1, 18, 8400])]
+#: `gh_fall_tonlong.onnx`, measured: 11 channels over 8400 anchors.
+ANCHOR_FALL = [Out("output0", [1, 11, 8400])]
+END2END = [Out("output0", [1, 300, 6])]
+
+#: `gh_fall_tonlong.onnx`'s own `names` metadata, byte for byte. SEVEN slots,
+#: and `Violence`/`violence` fold to ONE canonical name.
+FALL_NAMES = {0: "Violence", 1: "fall", 2: "fire", 3: "sit", 4: "sleep", 5: "standing", 6: "violence"}
+
+
+@contextlib.contextmanager
+def _captured_stdout():
+    buf = io.StringIO()
+    original = sys.stdout
+    sys.stdout = buf
+    try:
+        yield buf
+    finally:
+        sys.stdout = original
+
+
+class ProbeCase(unittest.TestCase):
+    """Shared helpers: the probe refuses by writing JSON and exiting 1."""
+
+    def args(self, *argv):
+        """A parsed `Namespace` through the REAL CLI, never a hand-built stand-in.
+
+        Every case that pretends to be a command line has to go through the
+        parser the command line goes through, or the suite stops covering the
+        surface it claims to.
+        """
+        return PROBE.parse_args(["--artifact", "unused.onnx", *argv])
+
+    def assertRefuses(self, fn, *args, **kwargs):
+        """Run something expected to `_fail`, and return its refusal payload.
+
+        Asserts the WHOLE contract of a refusal, not merely that it happened:
+        `{"ok": false, "step": ..., "reason": ...}` on stdout and exit 1. The
+        publisher reads `reason` off the LAST stdout line of a non-zero exit, so
+        a refusal that raised instead — or exited 0, or wrote prose — would reach
+        it as "the probe failed" with a stack trace attached.
+        """
+        with _captured_stdout() as buf:
+            with self.assertRaises(SystemExit) as raised:
+                fn(*args, **kwargs)
+        self.assertEqual(raised.exception.code, 1)
+        lines = [line for line in buf.getvalue().splitlines() if line.strip()]
+        self.assertTrue(lines, "a refusal must write JSON on stdout")
+        payload = json.loads(lines[-1])
+        self.assertIs(payload["ok"], False)
+        self.assertTrue(payload["step"])
+        self.assertTrue(payload["reason"])
+        return payload
+
+
+@unittest.skipIf(PROBE is None, NO_PROBE)
+class TestTheDefaultDidNotMove(ProbeCase):
+    """`--artifact` alone must answer exactly as it did before layouts existed.
+
+    `rfdetr_medium` was published by a run that passed nothing else, and its
+    `coco_classes`, `resident_mb` and graph contract are committed against that
+    run. A widened default would republish different numbers under the same
+    provenance, which is worse than a refusal because nothing would notice.
+    """
+
+    def test_no_declaration_is_the_rfdetr_contract(self):
+        contract, source = PROBE._resolve_variant(labels_mod, self.args())
+        self.assertEqual(contract.output_layout, labels_mod.RFDETR_DETS_LABELS)
+        self.assertEqual(contract.box_units, labels_mod.BOX_UNITS_PIXELS)
+        self.assertEqual(contract.box_scale_to_pixels, 1.0)
+        self.assertIn("default", source)
+
+    def test_a_graph_with_no_labels_output_is_still_refused(self):
+        reason = self.assertRefuses(
+            PROBE._graph_class_axis, labels_mod, labels_mod.RFDETR_DETS_LABELS, ANCHOR_14,
+        )["reason"]
+        # The refusal that has always been here, and the fact that identifies it.
+        self.assertIn("`labels`", reason)
+        # It now also says what to do about it, because there IS something.
+        self.assertIn("--variant-from-card", reason)
+        self.assertIn("output0[1, 18, 8400]", reason)
+
+    def test_the_rfdetr_class_axis_is_still_read_off_labels(self):
+        self.assertEqual(
+            PROBE._graph_class_axis(labels_mod, labels_mod.RFDETR_DETS_LABELS, DETS_LABELS_91),
+            91,
+        )
+
+    def test_a_dynamic_rfdetr_class_axis_is_still_refused(self):
+        outputs = [Out("dets", [1, 300, 4]), Out("labels", [1, 300, "num_classes"])]
+        reason = self.assertRefuses(
+            PROBE._graph_class_axis, labels_mod, labels_mod.RFDETR_DETS_LABELS, outputs,
+        )["reason"]
+        self.assertIn("fixed class axis", reason)
+
+
+@unittest.skipIf(PROBE is None, NO_PROBE)
+class TestDeclaredLayoutIsVerified(ProbeCase):
+    """Each layout accepted on a shape it can speak, refused on one it cannot.
+
+    The refusals name the DECLARED layout and the ACTUAL outputs, because those
+    two facts are what tells an operator whether the artifact is wrong or the
+    card is.
+    """
+
+    def test_anchor_accepted_and_its_class_axis_is_channels_minus_four(self):
+        self.assertEqual(
+            PROBE._graph_class_axis(labels_mod, labels_mod.ANCHOR_4_PLUS_NC, ANCHOR_14), 14,
+        )
+
+    def test_end2end_accepted_and_declares_no_class_axis(self):
+        # `None`, not 0 and not a guess: the class index rides in column 5, so
+        # the graph says nothing at all about how many classes this model has.
+        self.assertIsNone(
+            PROBE._graph_class_axis(labels_mod, labels_mod.END2END_N_6, END2END),
+        )
+
+    def test_anchor_refused_on_an_end2end_shape(self):
+        # THE DISAMBIGUATOR. `[1, 300, 6]` read as an anchor head is 296 classes
+        # over 6 anchors and decodes without raising.
+        reason = self.assertRefuses(
+            PROBE._graph_class_axis, labels_mod, labels_mod.ANCHOR_4_PLUS_NC, END2END,
+        )["reason"]
+        self.assertIn(labels_mod.ANCHOR_4_PLUS_NC, reason)
+        self.assertIn("output0[1, 300, 6]", reason)
+        self.assertIn("296 classes over 6 anchors", reason)
+
+    def test_end2end_refused_on_an_anchor_shape(self):
+        reason = self.assertRefuses(
+            PROBE._graph_class_axis, labels_mod, labels_mod.END2END_N_6, ANCHOR_FALL,
+        )["reason"]
+        self.assertIn(labels_mod.END2END_N_6, reason)
+        self.assertIn("output0[1, 11, 8400]", reason)
+
+    def test_rfdetr_refused_on_an_anchor_shape(self):
+        reason = self.assertRefuses(
+            PROBE._graph_class_axis, labels_mod, labels_mod.RFDETR_DETS_LABELS, ANCHOR_FALL,
+        )["reason"]
+        self.assertIn(labels_mod.RFDETR_DETS_LABELS, reason)
+
+    def test_a_single_output_layout_refuses_a_two_output_graph(self):
+        outputs = [Out("output0", [1, 18, 8400]), Out("proto", [1, 32, 160, 160])]
+        reason = self.assertRefuses(
+            PROBE._graph_class_axis, labels_mod, labels_mod.ANCHOR_4_PLUS_NC, outputs,
+        )["reason"]
+        self.assertIn("exactly ONE graph output", reason)
+        self.assertIn("proto", reason)
+
+    def test_anchor_refuses_a_rank_two_output(self):
+        reason = self.assertRefuses(
+            PROBE._graph_class_axis, labels_mod, labels_mod.ANCHOR_4_PLUS_NC, [Out("output0", [18, 8400])],
+        )["reason"]
+        self.assertIn("rank-3", reason)
+
+    def test_anchor_refuses_a_batch_that_is_not_one(self):
+        reason = self.assertRefuses(
+            PROBE._graph_class_axis, labels_mod, labels_mod.ANCHOR_4_PLUS_NC, [Out("output0", [4, 18, 8400])],
+        )["reason"]
+        self.assertIn("batch-1", reason)
+
+    def test_anchor_refuses_a_dynamic_class_axis(self):
+        # The class count is one of the two numbers a detector arm is meaningless
+        # without, and a symbolic axis does not carry it.
+        reason = self.assertRefuses(
+            PROBE._graph_class_axis, labels_mod, labels_mod.ANCHOR_4_PLUS_NC,
+            [Out("output0", [1, "channels", 8400])],
+        )["reason"]
+        self.assertIn("dynamic", reason)
+
+    def test_anchor_refuses_box_channels_with_no_class_left(self):
+        reason = self.assertRefuses(
+            PROBE._graph_class_axis, labels_mod, labels_mod.ANCHOR_4_PLUS_NC, [Out("output0", [1, 4, 8400])],
+        )["reason"]
+        self.assertIn("at least one class", reason)
+
+    def test_a_dynamic_anchor_count_does_not_block_a_real_head(self):
+        # `anchors > channels` is skipped rather than guessed when the axis is
+        # symbolic. The tensor ORT actually returns is still checked by
+        # `decode_anchor_4_plus_nc`'s own `expected_classes` refusal.
+        self.assertEqual(
+            PROBE._graph_class_axis(
+                labels_mod, labels_mod.ANCHOR_4_PLUS_NC, [Out("output0", [1, 18, "anchors"])],
+            ),
+            14,
+        )
+
+
+@unittest.skipIf(PROBE is None, NO_PROBE)
+class TestFourPlusNcCountsLogitSlots(ProbeCase):
+    """`4 + nc` where nc is the LOGIT WIDTH — never the number of distinct names.
+
+    This is the case that would silently invert the check. Both directions are
+    live on real artifacts:
+
+      * COCO-91 names 80 classes on a 91-wide axis (gaps in the category ids);
+      * `gh_fall_tonlong` declares SEVEN slots of which `Violence` and `violence`
+        fold to one canonical name, so it has 7 logit slots and 6 names.
+
+    Its graph is `[1, 11, 8400]`. `4 + 7` is 11 and matches; `4 + 6` is 10 and
+    would reject a perfectly healthy head.
+
+    `_verify_class_axis_width` passes by construction on a real run — the width it
+    is handed was read off the same graph — so these cases are what EXERCISES it.
+    That is the point of it: it is a tripwire on the derivation, and a tripwire
+    nothing pulls is indistinguishable from one that is wired wrong.
+    """
+
+    def test_the_fall_artifact_has_seven_slots_and_six_names(self):
+        slot_map = PROBE._canonical_slot_map(labels_mod, FALL_NAMES)
+        self.assertEqual(len(slot_map), 7)
+        self.assertEqual(len(set(slot_map.values())), 6)
+        self.assertEqual(slot_map[0], slot_map[6])
+
+    def test_the_logit_width_matches_the_real_graph(self):
+        # No refusal: this is the healthy case, and it must stay healthy.
+        PROBE._verify_class_axis_width(
+            labels_mod, labels_mod.ANCHOR_4_PLUS_NC, ANCHOR_FALL, 7,
+        )
+
+    def test_the_distinct_name_count_would_reject_the_same_graph(self):
+        reason = self.assertRefuses(
+            PROBE._verify_class_axis_width,
+            labels_mod, labels_mod.ANCHOR_4_PLUS_NC, ANCHOR_FALL, 6,
+        )["reason"]
+        self.assertIn("11 wide", reason)
+        self.assertIn("needs 10", reason)
+
+    def test_a_committed_vocabulary_narrower_than_the_graph_is_refused(self):
+        reason = self.assertRefuses(
+            PROBE._verify_class_axis_width,
+            labels_mod, labels_mod.ANCHOR_4_PLUS_NC, ANCHOR_14, 13,
+        )["reason"]
+        self.assertIn("18 wide", reason)
+        self.assertIn("needs 17", reason)
+
+    def test_rfdetr_width_is_checked_against_the_labels_axis(self):
+        PROBE._verify_class_axis_width(
+            labels_mod, labels_mod.RFDETR_DETS_LABELS, DETS_LABELS_91, 91,
+        )
+        reason = self.assertRefuses(
+            PROBE._verify_class_axis_width,
+            labels_mod, labels_mod.RFDETR_DETS_LABELS, DETS_LABELS_91, 80,
+        )["reason"]
+        # COCO-91 names EIGHTY classes on a NINETY-ONE-wide axis, so the name
+        # count is the wrong number here too — in the other direction.
+        self.assertIn("91 wide", reason)
+
+    def test_end2end_has_no_width_to_check(self):
+        # Not an omission: the class index is a column, so any width is
+        # consistent with the graph and a check would be theatre.
+        PROBE._verify_class_axis_width(labels_mod, labels_mod.END2END_N_6, END2END, 3)
+        PROBE._verify_class_axis_width(labels_mod, labels_mod.END2END_N_6, END2END, 91)
+
+    def test_a_vocabulary_with_two_spellings_of_one_word_is_unpublishable(self):
+        # The other half of the same artifact: the SHAPE is fine, the LIST is
+        # not, and `ModelVocabulary` refuses it at construction on a device too.
+        with self.assertRaises(ValueError) as raised:
+            PROBE._build_vocabulary(
+                labels_mod,
+                "fall_specialist",
+                PROBE._canonical_slot_map(labels_mod, FALL_NAMES),
+                7,
+                labels_mod.VariantContract(
+                    labels_mod.ANCHOR_4_PLUS_NC, labels_mod.BOX_UNITS_PIXELS, 1.0,
+                ),
+            )
+        self.assertIn("two slots share one class name", str(raised.exception))
+
+
+@unittest.skipIf(PROBE is None, NO_PROBE)
+class TestBoxUnitsAreRecordedNeverInvented(ProbeCase):
+    """A coordinate space is declared or the run is refused. It is never guessed.
+
+    `session.py` multiplies by `box_scale_to_pixels` and draws, without ever
+    re-deriving from the tensor, so a defaulted value is a 640x error that raises
+    nothing on an unpadded frame. RF-DETR is the one exemption and it is
+    structural: its branch calls `postprocess`, which does its own
+    normalised-to-frame scaling and never reads the contract.
+    """
+
+    def test_a_non_rfdetr_layout_without_box_units_is_refused(self):
+        reason = self.assertRefuses(
+            PROBE._resolve_variant, labels_mod, self.args("--output-layout", labels_mod.ANCHOR_4_PLUS_NC),
+        )["reason"]
+        self.assertIn("--box-units", reason)
+        self.assertIn("640x too small", reason)
+
+    def test_end2end_without_box_units_is_refused_too(self):
+        self.assertRefuses(
+            PROBE._resolve_variant, labels_mod, self.args("--output-layout", labels_mod.END2END_N_6),
+        )
+
+    def test_normalized_without_a_scale_is_refused(self):
+        # 1.0 IS positive, so `VariantContract` would accept the default and the
+        # boxes would be silently wrong. The refusal has to happen before it.
+        reason = self.assertRefuses(
+            PROBE._resolve_variant, labels_mod,
+            self.args("--output-layout", labels_mod.ANCHOR_4_PLUS_NC, "--box-units", "normalized"),
+        )["reason"]
+        self.assertIn("--box-scale-to-pixels", reason)
+
+    def test_normalized_with_a_scale_is_carried_through(self):
+        contract, source = PROBE._resolve_variant(labels_mod, self.args(
+            "--output-layout", labels_mod.ANCHOR_4_PLUS_NC,
+            "--box-units", "normalized", "--box-scale-to-pixels", "640",
+        ))
+        self.assertEqual(contract.box_units, labels_mod.BOX_UNITS_NORMALIZED)
+        self.assertEqual(contract.box_scale_to_pixels, 640.0)
+        self.assertIn("--output-layout", source)
+
+    def test_pixels_with_a_scale_that_is_not_one_is_refused(self):
+        reason = self.assertRefuses(
+            PROBE._resolve_variant, labels_mod,
+            self.args("--output-layout", labels_mod.ANCHOR_4_PLUS_NC,
+                      "--box-units", "pixels", "--box-scale-to-pixels", "640"),
+        )["reason"]
+        self.assertIn("already pixels", reason)
+
+    def test_a_scale_without_units_is_refused_rather_than_overwritten(self):
+        # RF-DETR is the one layout whose units may be omitted, so it is also the
+        # one place a declared scale could be silently replaced by the 1.0 that
+        # fallback supplies. A declaration accepted and discarded is worse than a
+        # refusal: nothing downstream can tell it happened.
+        reason = self.assertRefuses(
+            PROBE._resolve_variant, labels_mod,
+            self.args("--output-layout", labels_mod.RFDETR_DETS_LABELS, "--box-scale-to-pixels", "640"),
+        )["reason"]
+        self.assertIn("no box_units", reason)
+        self.assertIn("640", reason)
+
+    def test_units_without_a_layout_are_a_claim_about_nothing(self):
+        reason = self.assertRefuses(
+            PROBE._resolve_variant, labels_mod, self.args("--box-units", "pixels"),
+        )["reason"]
+        self.assertIn("--output-layout", reason)
+
+    def test_an_unknown_layout_is_refused_by_name(self):
+        reason = self.assertRefuses(
+            PROBE._resolve_variant, labels_mod, self.args("--output-layout", "yolo_v8_raw"),
+        )["reason"]
+        self.assertIn("yolo_v8_raw", reason)
+
+    def test_an_unknown_box_unit_is_refused_by_name(self):
+        reason = self.assertRefuses(
+            PROBE._resolve_variant, labels_mod,
+            self.args("--output-layout", labels_mod.ANCHOR_4_PLUS_NC, "--box-units", "pixel"),
+        )["reason"]
+        self.assertIn("'pixel'", reason)
+
+
+@unittest.skipIf(PROBE is None, NO_PROBE)
+class TestVariantFromCard(ProbeCase):
+    """The card is the primary path: a MEASUREMENT with provenance, not a claim."""
+
+    def _card(self, variant, **extra):
+        handle = tempfile.NamedTemporaryFile("w", suffix=".json", delete=False)
+        blob = {"schema": "detector-score-card/1", "verdict": {"publishable": True}}
+        blob.update(extra)
+        if variant is not None:
+            blob["variant"] = variant
+        json.dump(blob, handle)
+        handle.close()
+        self.addCleanup(lambda: pathlib.Path(handle.name).unlink(missing_ok=True))
+        return handle.name
+
+    #: The `variant` block `score-detector-candidate.js` wrote for every one of
+    #: the five staged specialists, verbatim in shape.
+    MEASURED = {
+        "format": "onnx",
+        "output_layout": "anchor_4_plus_nc",
+        "end2end": False,
+        "box_units": "pixels",
+        "box_scale_to_pixels": 1,
+        "box_units_evidence": "max|box channel| = 640.0000 over 110 real frames",
+    }
+
+    def test_the_three_values_are_read_off_the_card(self):
+        contract, source = PROBE._resolve_variant(
+            labels_mod, self.args("--variant-from-card", self._card(self.MEASURED)),
+        )
+        self.assertEqual(contract.output_layout, labels_mod.ANCHOR_4_PLUS_NC)
+        self.assertEqual(contract.box_units, labels_mod.BOX_UNITS_PIXELS)
+        # A JSON `1` is a scale of 1.0. `VariantContract` compares it against
+        # 1.0 exactly, so the coercion is load-bearing rather than cosmetic.
+        self.assertEqual(contract.box_scale_to_pixels, 1.0)
+        self.assertIn("--variant-from-card", source)
+
+    def test_a_card_with_no_variant_block_is_refused(self):
+        reason = self.assertRefuses(
+            PROBE._resolve_variant, labels_mod, self.args("--variant-from-card", self._card(None)),
+        )["reason"]
+        self.assertIn("no `variant` block", reason)
+
+    def test_a_partial_variant_block_is_refused(self):
+        partial = {k: v for k, v in self.MEASURED.items() if k != "box_units"}
+        reason = self.assertRefuses(
+            PROBE._resolve_variant, labels_mod, self.args("--variant-from-card", self._card(partial)),
+        )["reason"]
+        self.assertIn("variant.box_units", reason)
+
+    def test_unreadable_json_is_refused_rather_than_raised(self):
+        handle = tempfile.NamedTemporaryFile("w", suffix=".json", delete=False)
+        handle.write("{not json")
+        handle.close()
+        self.addCleanup(lambda: pathlib.Path(handle.name).unlink(missing_ok=True))
+        self.assertRefuses(
+            PROBE._resolve_variant, labels_mod, self.args("--variant-from-card", handle.name),
+        )
+
+    def test_a_card_and_a_flag_that_AGREE_are_fine(self):
+        contract, source = PROBE._resolve_variant(labels_mod, self.args(
+            "--variant-from-card", self._card(self.MEASURED),
+            "--output-layout", labels_mod.ANCHOR_4_PLUS_NC,
+        ))
+        self.assertEqual(contract.output_layout, labels_mod.ANCHOR_4_PLUS_NC)
+        # A flag that states ONE field must not read as disagreeing with a card
+        # that states three — the agreement is checked per field, not per tuple.
+        self.assertIn("--variant-from-card", source)
+
+    def test_a_card_and_a_flag_that_DISAGREE_are_refused(self):
+        reason = self.assertRefuses(PROBE._resolve_variant, labels_mod, self.args(
+            "--variant-from-card", self._card(self.MEASURED),
+            "--output-layout", labels_mod.END2END_N_6,
+        ))["reason"]
+        self.assertIn("DISAGREES", reason)
+        self.assertIn(labels_mod.ANCHOR_4_PLUS_NC, reason)
+        self.assertIn(labels_mod.END2END_N_6, reason)
+
+    def test_a_disagreeing_scale_is_refused_too(self):
+        normalized = dict(self.MEASURED, box_units="normalized", box_scale_to_pixels=640)
+        reason = self.assertRefuses(PROBE._resolve_variant, labels_mod, self.args(
+            "--variant-from-card", self._card(normalized),
+            "--output-layout", labels_mod.ANCHOR_4_PLUS_NC,
+            "--box-units", "normalized", "--box-scale-to-pixels", "320",
+        ))["reason"]
+        self.assertIn("box_scale_to_pixels", reason)
+
+
+@unittest.skipIf(PROBE is None, NO_PROBE)
+class TestClassAxisWidthWhenTheGraphDeclaresNone(ProbeCase):
+    """`end2end_n_6` has no class axis, so the width comes from the class LIST."""
+
+    def _classes_file(self, blob):
+        handle = tempfile.NamedTemporaryFile("w", suffix=".json", delete=False)
+        json.dump(blob, handle)
+        handle.close()
+        self.addCleanup(lambda: pathlib.Path(handle.name).unlink(missing_ok=True))
+        return handle.name
+
+    def test_a_dense_list_sets_the_width_to_one_past_its_last_slot(self):
+        args = self.args("--classes-file", self._classes_file(["forklift", "pallet", "person"]))
+        slot_names, source, width = PROBE._resolve_slot_names(
+            labels_mod, args, None, "(no graph metadata)", None,
+        )
+        self.assertEqual(slot_names, {0: "forklift", 1: "pallet", 2: "person"})
+        self.assertIn("--classes-file", source)
+        self.assertEqual(width, 3)
+
+    def test_a_sparse_map_sets_the_width_from_its_highest_slot(self):
+        args = self.args("--classes-file", self._classes_file({"0": "forklift", "9": "person"}))
+        _, _, width = PROBE._resolve_slot_names(labels_mod, args, None, "(no graph metadata)", None)
+        self.assertEqual(width, 10)
+
+    def test_a_graph_declaring_fewer_names_than_its_axis_is_still_ambiguous(self):
+        # The check that DOES depend on a width, unchanged: it fires whenever the
+        # graph declares one, and is skipped only when the layout carries none.
+        args = self.args()
+        reason = self.assertRefuses(
+            PROBE._resolve_slot_names, labels_mod, args, ["person", "car"], "graph metadata key 'names'", 91,
+        )["reason"]
+        self.assertIn("--slot-offset", reason)
+
+    def test_the_same_list_is_unambiguous_when_the_graph_declares_no_axis(self):
+        args = self.args()
+        slot_names, _, width = PROBE._resolve_slot_names(
+            labels_mod, args, ["person", "car"], "graph metadata key 'names'", None,
+        )
+        self.assertEqual(slot_names, {0: "person", 1: "car"})
+        self.assertEqual(width, 2)
+
+
+@unittest.skipIf(PROBE is None, NO_PROBE)
+class TestTheCliSurface(ProbeCase):
+    """The flags this script offers, asserted so a rename cannot be silent.
+
+    `publish-sensing-model.js` builds `--variant-from-card` by hand into an
+    `argv` array and reads the probe's stdout back. Nothing type-checks that
+    join, so a flag renamed on one side surfaces as "the probe failed" with an
+    argparse usage string attached — at publish time, on a real artifact.
+    """
+
+    EXPECTED = {
+        "-h", "--help", "--mode", "--measure-payload", "--artifact", "--model-id",
+        "--classes-file", "--slot-offset",
+        "--variant-from-card", "--output-layout", "--box-units", "--box-scale-to-pixels",
+    }
+
+    def test_the_option_strings_are_exactly_these(self):
+        offered = set()
+        for action in PROBE.build_parser()._actions:
+            offered.update(action.option_strings)
+        self.assertEqual(offered, self.EXPECTED)
+
+    def test_the_declaration_flags_all_default_to_none(self):
+        # NOT to the RF-DETR values. `_resolve_variant` has to be able to tell
+        # "nobody declared a layout" from "somebody declared this one", because
+        # only the first may fall back to a default.
+        args = self.args()
+        self.assertIsNone(args.variant_from_card)
+        self.assertIsNone(args.output_layout)
+        self.assertIsNone(args.box_units)
+        self.assertIsNone(args.box_scale_to_pixels)
+
+    def test_slot_offset_still_records_whether_it_was_typed(self):
+        self.assertFalse(self.args().slot_offset_given)
+        self.assertEqual(self.args().slot_offset, 0)
+        typed = self.args("--slot-offset", "0")
+        self.assertTrue(typed.slot_offset_given)
+        self.assertEqual(typed.slot_offset, 0)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    unittest.main()