@trillboards/edge-sdk 0.2.91 → 0.2.92

package/deploy/detector/bench/box_units.py

@@ -0,0 +1,71 @@
+"""What a box coordinate MEANS, decided from a forward pass — STDLIB ONLY.
+
+Split out of `run_candidate.py` so the `detector-service` CI lane can reach it.
+That lane runs `python3 -m unittest discover` with NO pip install, and
+`run_candidate.py` imports `trillboards_detector.session` and therefore
+onnxruntime at module scope — so a test importing it does not skip, it errors
+the whole lane during discovery. The decision lives here in stdlib; the forward
+pass that produces `box_abs_max` stays there.
+
+Same split, and the same reason, as `bench/twin_parity_contract.py`.
+"""
+
+from __future__ import annotations
+
+
+#: LiteRT boxes in 0..1, agreeing to 0.00266 px after multiplying by 640, while
+#: their CLASS channels agree to 1.2e-07. `queue_supermarket`, the one end2end
+#: twin, agrees on both sides — end2end heads emit pixels everywhere.
+#:
+#: Every check a publish gate would otherwise run PASSES on that pair: same
+#: output shape, same dtype, loads, runs, class scores identical. An Android
+#: post-processor reusing the ONNX decode draws every box 640x too small and
+#: nothing reports an error. So the units are MEASURED from a forward pass, per
+#: artifact, and recorded — never carried across from the sibling format.
+#:
+#: The discriminator is a ratio, max|box channel| / imgsz, and it is decisive by
+#: two and a half orders of magnitude. Measured over 119 ONNX artifacts the ratio
+#: spans 0.988..1.167; a normalised head sits at ~1/640 = 0.0016. The dead zone
+#: below is EMPTY across every artifact in the tree, and an artifact landing in it
+#: is refused rather than guessed at — that is the whole point of the field.
+BOX_UNITS_PIXEL_RATIO_MIN = 0.2
+BOX_UNITS_NORMALIZED_RATIO_MAX = 0.02
+
+
+def classify_box_units(box_abs_max: float, imgsz: int) -> dict:
+    """pixels, normalized, or REFUSE — never a guess.
+
+    Returns the verdict plus the evidence, because a bare enum in a score card is
+    a claim and the ratio is what makes it checkable.
+    """
+    # `<= 0.0` MATTERS AS MUCH AS `is None`, and it is the case that actually
+    # happens. 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, `box_abs_max` stays at its
+    # 0.0 seed, and the ratio 0.0/imgsz lands under BOX_UNITS_NORMALIZED_RATIO_MAX.
+    # The old predicate then returned a CONFIDENT `normalized` with
+    # scale_to_pixels=640 from zero observations, and that declaration is exactly
+    # what `session.py` now trusts absolutely: the layout and units are DECLARED
+    # by the variant contract and never re-derived from the tensor. So a dead
+    # artifact published a coordinate-space claim no frame supports.
+    #
+    # The refusal string below already described this case. It just could not be
+    # reached, which is the whole shape of the defect this function exists to
+    # prevent — a check that runs, passes, and measures nothing.
+    if imgsz <= 0 or box_abs_max is None or box_abs_max <= 0.0:
+        return {"units": None, "ratio": None, "scale_to_pixels": None,
+                "refusal": "no box channels were observed, so the coordinate space is unmeasured"}
+    ratio = box_abs_max / imgsz
+    if ratio >= BOX_UNITS_PIXEL_RATIO_MIN:
+        return {"units": "pixels", "ratio": ratio, "scale_to_pixels": 1.0, "refusal": None}
+    if ratio <= BOX_UNITS_NORMALIZED_RATIO_MAX:
+        return {"units": "normalized", "ratio": ratio, "scale_to_pixels": float(imgsz), "refusal": None}
+    return {
+        "units": None, "ratio": ratio, "scale_to_pixels": None,
+        "refusal": (
+            f"max|box|/imgsz = {ratio:.4f} falls between {BOX_UNITS_NORMALIZED_RATIO_MAX} and "
+            f"{BOX_UNITS_PIXEL_RATIO_MIN}, where neither pixels nor normalised is credible. "
+            "Measured over 119 artifacts this band is empty; refusing rather than picking one, "
+            "because the wrong pick is silent and scales every box by 640."
+        ),
+    }

package/deploy/detector/bench/run_candidate.py

@@ -82,7 +82,13 @@ import time
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent.parent))  # noqa: E402
+sys.path.insert(0, str(Path(__file__).resolve().parent))  # noqa: E402  (bench siblings)
 
+from box_units import (  # noqa: E402  (sibling module, stdlib-only on purpose)
+    BOX_UNITS_NORMALIZED_RATIO_MAX,
+    BOX_UNITS_PIXEL_RATIO_MIN,
+    classify_box_units,
+)
 from trillboards_detector.errors import ModelContractError  # noqa: E402
 from trillboards_detector.labels import (  # noqa: E402
     BOX_UNITS_PIXELS,
@@ -107,23 +113,7 @@ SCHEMA = "detector-candidate-run/2"
 #: Ultralytics' TFLite export path wraps a `task=detect`, `end2end=False` model in
 #: `_NormalizeCoords`, dividing the four box channels by (W, H). Measured here on
 #: all 17 committed LiteRT twins: 16 of 17 have ONNX boxes in pixels 0..640 and
-#: LiteRT boxes in 0..1, agreeing to 0.00266 px after multiplying by 640, while
-#: their CLASS channels agree to 1.2e-07. `queue_supermarket`, the one end2end
-#: twin, agrees on both sides — end2end heads emit pixels everywhere.
-#:
-#: Every check a publish gate would otherwise run PASSES on that pair: same
-#: output shape, same dtype, loads, runs, class scores identical. An Android
-#: post-processor reusing the ONNX decode draws every box 640x too small and
-#: nothing reports an error. So the units are MEASURED from a forward pass, per
-#: artifact, and recorded — never carried across from the sibling format.
-#:
-#: The discriminator is a ratio, max|box channel| / imgsz, and it is decisive by
-#: two and a half orders of magnitude. Measured over 119 ONNX artifacts the ratio
-#: spans 0.988..1.167; a normalised head sits at ~1/640 = 0.0016. The dead zone
-#: below is EMPTY across every artifact in the tree, and an artifact landing in it
-#: is refused rather than guessed at — that is the whole point of the field.
-BOX_UNITS_PIXEL_RATIO_MIN = 0.2
-BOX_UNITS_NORMALIZED_RATIO_MAX = 0.02
+
 
 #: Warm-up forward passes before any timing is kept. ORT's first run pays for
 #: arena allocation and kernel selection; folding that into a p50 over 134 frames
@@ -271,31 +261,6 @@ def classify_output_layout(output_shapes: "list[list]") -> str:
     return f"unknown_rank_{len(shape)}"
 
 
-def classify_box_units(box_abs_max: float, imgsz: int) -> dict:
-    """pixels, normalized, or REFUSE — never a guess.
-
-    Returns the verdict plus the evidence, because a bare enum in a score card is
-    a claim and the ratio is what makes it checkable.
-    """
-    if imgsz <= 0 or box_abs_max is None:
-        return {"units": None, "ratio": None, "scale_to_pixels": None,
-                "refusal": "no box channels were observed, so the coordinate space is unmeasured"}
-    ratio = box_abs_max / imgsz
-    if ratio >= BOX_UNITS_PIXEL_RATIO_MIN:
-        return {"units": "pixels", "ratio": ratio, "scale_to_pixels": 1.0, "refusal": None}
-    if ratio <= BOX_UNITS_NORMALIZED_RATIO_MAX:
-        return {"units": "normalized", "ratio": ratio, "scale_to_pixels": float(imgsz), "refusal": None}
-    return {
-        "units": None, "ratio": ratio, "scale_to_pixels": None,
-        "refusal": (
-            f"max|box|/imgsz = {ratio:.4f} falls between {BOX_UNITS_NORMALIZED_RATIO_MAX} and "
-            f"{BOX_UNITS_PIXEL_RATIO_MIN}, where neither pixels nor normalised is credible. "
-            "Measured over 119 artifacts this band is empty; refusing rather than picking one, "
-            "because the wrong pick is silent and scales every box by 640."
-        ),
-    }
-
-
 def letterbox(image, width: int, height: int):
     """Ultralytics' resize: scale to fit, pad the remainder 114-grey, centred.
 

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/dist/EdgeAgent.js

@@ -44,7 +44,7 @@ const edge_ads_1 = require("@trillboards/edge-ads");
 const CommandRouter_1 = require("./CommandRouter");
 const config_1 = require("./config");
 const dataDir_1 = require("./dataDir");
-const SDK_VERSION = '0.2.91';
+const SDK_VERSION = '0.2.92';
 class EdgeAgent extends events_1.EventEmitter {
     constructor(config, deps) {
         super();

package/dist/diagnose.d.ts

@@ -31,7 +31,7 @@ export interface DiagnosticReport {
         skipped: number;
     };
 }
-declare const SDK_VERSION = "0.2.91";
+declare const SDK_VERSION = "0.2.92";
 declare function checkNodeVersion(): CheckResult;
 declare function checkPlatform(): CheckResult;
 declare function checkMemory(): CheckResult;

package/dist/diagnose.js

@@ -63,7 +63,7 @@ const localNetworkAccess_1 = require("./localNetworkAccess");
 // ---------------------------------------------------------------------------
 // SDK version — mirrors package.json; kept in sync by CI
 // ---------------------------------------------------------------------------
-const SDK_VERSION = '0.2.91';
+const SDK_VERSION = '0.2.92';
 exports._SDK_VERSION = SDK_VERSION;
 // ---------------------------------------------------------------------------
 // ANSI helpers (no external deps)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trillboards/edge-sdk",
-  "version": "0.2.91",
+  "version": "0.2.92",
   "description": "Composable cross-platform Edge AI SDK for audience sensing on DOOH/CTV devices",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",