@trillboards/edge-sdk 0.2.92 → 0.2.94

package/deploy/detector/bench/litert-twin-parity.json

@@ -0,0 +1,313 @@
+{
+  "_comment": [
+    "MEASURED, not asserted. Produced by bench/verify_litert_twin_parity.py on 2026-08-25,",
+    "one fp32 input tensor fed to both runtimes (onnxruntime 1.29.0 CPU, ai-edge-litert),",
+    "seed 1234, both taking NCHW [1,3,640,640] \u2014 the LiteRT export of an ultralytics detect",
+    "model is NOT NHWC.",
+    "",
+    "THE RESULT: the box scale is a property of the LAYOUT, not of the runtime.",
+    "  anchor_4_plus_nc  LiteRT boxes are NORMALISED; box*imgsz recovers ONNX pixels",
+    "                    to <= 0.00588 px, and the class channels already agree to",
+    "                    <= 4.2e-06 with no scaling at all.",
+    "  end2end_n_6       the _NormalizeCoords wrapper is NOT applied; both runtimes",
+    "                    emit pixels, so the scale is 1.0.",
+    "A decoder that scales every LiteRT model is exactly as wrong as one that scales",
+    "none \u2014 it just corrupts the other half of the library, and silently, because",
+    "shape, dtype, class count and every score still match.",
+    "",
+    "queue_supermarket is recorded FAILING on purpose. Its box value RANGE is identical",
+    "in both runtimes and already in pixels (litert [-45.104, 652.062], onnx the same) and",
+    "its scores agree to 7.2e-08, but row-wise the two disagree and lexsorting by box does",
+    "not collapse it. The model returns ZERO detections above 0.25 on 40 real production",
+    "frames, so there is no above-threshold sample to compare and row-level parity is",
+    "UNVERIFIED. It is not published. Settle it on a corpus the model actually fires on."
+  ],
+  "measured_at": "2026-08-25",
+  "tolerances": {
+    "box_residual_px": 0.05,
+    "cls_residual": 0.0001
+  },
+  "box_scale_by_layout": {
+    "anchor_4_plus_nc": "imgsz",
+    "end2end_n_6": 1.0,
+    "rfdetr_dets_labels": 1.0
+  },
+  "twins": [
+    {
+      "layout": "anchor_4_plus_nc",
+      "imgsz": 640,
+      "box_scale_applied": 640.0,
+      "box_residual_px": 0.000865936279296875,
+      "box_residual_unscaled": 641.0272229909897,
+      "cls_residual": 1.996755599975586e-06,
+      "pass": true,
+      "reason": "ok",
+      "onnx": "apron_murugu.onnx",
+      "litert": "apron_murugu.tflite"
+    },
+    {
+      "layout": "anchor_4_plus_nc",
+      "imgsz": 640,
+      "box_scale_applied": 640.0,
+      "box_residual_px": 0.000476837158203125,
+      "box_residual_unscaled": 635.8220509290695,
+      "cls_residual": 1.1929387255804613e-07,
+      "pass": true,
+      "reason": "ok",
+      "onnx": "fall_posture_3cls_11n.onnx",
+      "litert": "fall_posture_3cls_11n.tflite"
+    },
+    {
+      "layout": "anchor_4_plus_nc",
+      "imgsz": 640,
+      "box_scale_applied": 640.0,
+      "box_residual_px": 0.0030517578125,
+      "box_residual_unscaled": 656.5295736789703,
+      "cls_residual": 6.020069122314453e-06,
+      "pass": true,
+      "reason": "ok",
+      "onnx": "fire_5cls_fpsuppress_11n.onnx",
+      "litert": "fire_5cls_fpsuppress_11n.tflite"
+    },
+    {
+      "layout": "anchor_4_plus_nc",
+      "imgsz": 640,
+      "box_scale_applied": 640.0,
+      "box_residual_px": 0.00335693359375,
+      "box_residual_unscaled": 635.6288108825684,
+      "cls_residual": 1.237494871020317e-07,
+      "pass": true,
+      "reason": "ok",
+      "onnx": "forklift_akdve_11n.onnx",
+      "litert": "forklift_akdve_11n.tflite"
+    },
+    {
+      "layout": "anchor_4_plus_nc",
+      "imgsz": 640,
+      "box_scale_applied": 640.0,
+      "box_residual_px": 0.001003265380859375,
+      "box_residual_unscaled": 651.8335539102554,
+      "cls_residual": 1.3380153518482985e-07,
+      "pass": true,
+      "reason": "ok",
+      "onnx": "gh_forklift_combine.onnx",
+      "litert": "gh_forklift_combine.tflite",
+      "model_id": "gh_forklift_combine",
+      "box_units": "normalized",
+      "box_scale_to_pixels": 640.0,
+      "litert_sha256": "c196a45613726e1a0bd522cd7140fde58784d71d9ffadfec00b033f8914b9df5",
+      "litert_bytes": 12257807,
+      "evidence": "twin parity: box residual 0.001003 px after x640, UNSCALED 651.8 px \u2014 the scale is load-bearing, not cosmetic. Class residual 1.34e-07 with no scaling at all."
+    },
+    {
+      "layout": "anchor_4_plus_nc",
+      "imgsz": 640,
+      "box_scale_applied": 640.0,
+      "box_residual_px": 0.001369476318359375,
+      "box_residual_unscaled": 634.430369079113,
+      "cls_residual": 1.3195858628023416e-07,
+      "pass": true,
+      "reason": "ok",
+      "onnx": "glove_madesh.onnx",
+      "litert": "glove_madesh.tflite"
+    },
+    {
+      "layout": "anchor_4_plus_nc",
+      "imgsz": 640,
+      "box_scale_applied": 640.0,
+      "box_residual_px": 0.00102996826171875,
+      "box_residual_unscaled": 648.4288479089737,
+      "cls_residual": 7.897615432739258e-07,
+      "pass": true,
+      "reason": "ok",
+      "onnx": "glove_sunita.onnx",
+      "litert": "glove_sunita.tflite"
+    },
+    {
+      "layout": "anchor_4_plus_nc",
+      "imgsz": 640,
+      "box_scale_applied": 640.0,
+      "box_residual_px": 0.0028209686279296875,
+      "box_residual_unscaled": 637.0318885445595,
+      "cls_residual": 1.6111880540847778e-07,
+      "pass": true,
+      "reason": "ok",
+      "onnx": "hf_crowd_irail.onnx",
+      "litert": "hf_crowd_irail.tflite"
+    },
+    {
+      "layout": "anchor_4_plus_nc",
+      "imgsz": 640,
+      "box_scale_applied": 640.0,
+      "box_residual_px": 0.001659393310546875,
+      "box_residual_unscaled": 639.9944154024124,
+      "cls_residual": 1.6391277313232422e-06,
+      "pass": true,
+      "reason": "ok",
+      "onnx": "hf_smoking.onnx",
+      "litert": "hf_smoking.tflite"
+    },
+    {
+      "layout": "anchor_4_plus_nc",
+      "imgsz": 640,
+      "box_scale_applied": 640.0,
+      "box_residual_px": 0.00424957275390625,
+      "box_residual_unscaled": 637.0888672471046,
+      "cls_residual": 1.2430425044840376e-07,
+      "pass": true,
+      "reason": "ok",
+      "onnx": "hg-v6.onnx",
+      "litert": "hg-v6.tflite"
+    },
+    {
+      "layout": "anchor_4_plus_nc",
+      "imgsz": 640,
+      "box_scale_applied": 640.0,
+      "box_residual_px": 0.001068115234375,
+      "box_residual_unscaled": 634.6248278617859,
+      "cls_residual": 1.2764758139383048e-07,
+      "pass": true,
+      "reason": "ok",
+      "onnx": "ppe_construction_17cls_v8n.onnx",
+      "litert": "ppe_construction_17cls_v8n.tflite",
+      "model_id": "ppe_construction_17cls_v8n",
+      "box_units": "normalized",
+      "box_scale_to_pixels": 640.0,
+      "litert_sha256": "08ebf94fec8c864eb4c1fae009d8f7686252c622fafed37c71d80f117884173b",
+      "litert_bytes": 12268767,
+      "evidence": "twin parity: box residual 0.001068 px after x640, UNSCALED 634.6 px \u2014 the scale is load-bearing, not cosmetic. Class residual 1.28e-07 with no scaling at all."
+    },
+    {
+      "layout": "anchor_4_plus_nc",
+      "imgsz": 640,
+      "box_scale_applied": 640.0,
+      "box_residual_px": 0.00177001953125,
+      "box_residual_unscaled": 638.4268003106117,
+      "cls_residual": 1.3917764363213792e-07,
+      "pass": true,
+      "reason": "ok",
+      "onnx": "ppe_keremberke_v8m.onnx",
+      "litert": "ppe_keremberke_v8m.tflite"
+    },
+    {
+      "layout": "anchor_4_plus_nc",
+      "imgsz": 640,
+      "box_scale_applied": 640.0,
+      "box_residual_px": 0.002044677734375,
+      "box_residual_unscaled": 663.3222885131836,
+      "cls_residual": 1.227854227181524e-07,
+      "pass": true,
+      "reason": "ok",
+      "onnx": "ppe_keremberke_v8n.onnx",
+      "litert": "ppe_keremberke_v8n.tflite"
+    },
+    {
+      "layout": "anchor_4_plus_nc",
+      "imgsz": 640,
+      "box_scale_applied": 640.0,
+      "box_residual_px": 0.00238800048828125,
+      "box_residual_unscaled": 652.3816465139389,
+      "cls_residual": 1.3384212138589646e-07,
+      "pass": true,
+      "reason": "ok",
+      "onnx": "ppe_keremberke_v8s.onnx",
+      "litert": "ppe_keremberke_v8s.tflite"
+    },
+    {
+      "layout": "anchor_4_plus_nc",
+      "imgsz": 640,
+      "box_scale_applied": 640.0,
+      "box_residual_px": 0.00225830078125,
+      "box_residual_unscaled": 641.4581891298294,
+      "cls_residual": 1.3920431740643835e-07,
+      "pass": true,
+      "reason": "ok",
+      "onnx": "ppe_killuminati_19cls_v8s.onnx",
+      "litert": "ppe_killuminati_19cls_v8s.tflite",
+      "model_id": "ppe_killuminati_19cls_v8s",
+      "box_units": "normalized",
+      "box_scale_to_pixels": 640.0,
+      "litert_sha256": "493f93835ba89904296f14b5dd8dc1451612ec319fdf968a29bede69b24debb5",
+      "litert_bytes": 44764391,
+      "evidence": "twin parity: box residual 0.002258 px after x640, UNSCALED 641.5 px \u2014 the scale is load-bearing, not cosmetic. Class residual 1.39e-07 with no scaling at all."
+    },
+    {
+      "layout": "anchor_4_plus_nc",
+      "imgsz": 640,
+      "box_scale_applied": 640.0,
+      "box_residual_px": 0.0002117156982421875,
+      "box_residual_unscaled": 636.5309634804726,
+      "cls_residual": 1.373183451391924e-07,
+      "pass": true,
+      "reason": "ok",
+      "onnx": "ppe_vyra_14cls_v8m.onnx",
+      "litert": "ppe_vyra_14cls_v8m.tflite",
+      "model_id": "ppe_vyra_14cls_v8m",
+      "box_units": "normalized",
+      "box_scale_to_pixels": 640.0,
+      "litert_sha256": "bef4efe403c834d1b05fa5217d97fcbcefde3da890b964141692fad66ca260f1",
+      "litert_bytes": 103663784,
+      "evidence": "twin parity: box residual 0.0002117 px after x640, UNSCALED 636.5 px \u2014 the scale is load-bearing, not cosmetic. Class residual 1.37e-07 with no scaling at all."
+    },
+    {
+      "layout": "end2end_n_6",
+      "imgsz": 640,
+      "box_scale_applied": 1.0,
+      "box_residual_px": 630.3428831100464,
+      "box_residual_unscaled": 630.3428831100464,
+      "cls_residual": 8.372444426640868e-08,
+      "pass": false,
+      "reason": "box residual 630.3 px exceeds 0.05 under layout end2end_n_6 (scale x1.0)",
+      "onnx": "queue_supermarket.onnx",
+      "litert": "queue_supermarket.tflite"
+    },
+    {
+      "layout": "anchor_4_plus_nc",
+      "imgsz": 640,
+      "box_scale_applied": 640.0,
+      "box_residual_px": 0.000308990478515625,
+      "box_residual_unscaled": 647.0199807882309,
+      "cls_residual": 1.218754732690286e-07,
+      "pass": true,
+      "reason": "ok",
+      "onnx": "shoplift_pavan.onnx",
+      "litert": "shoplift_pavan.tflite"
+    },
+    {
+      "layout": "anchor_4_plus_nc",
+      "imgsz": 640,
+      "box_scale_applied": 640.0,
+      "box_residual_px": 0.000621795654296875,
+      "box_residual_unscaled": 634.978705227375,
+      "cls_residual": 1.3541824728235952e-07,
+      "pass": true,
+      "reason": "ok",
+      "onnx": "spill_fluid.onnx",
+      "litert": "spill_fluid.tflite"
+    },
+    {
+      "layout": "anchor_4_plus_nc",
+      "imgsz": 640,
+      "box_scale_applied": 640.0,
+      "box_residual_px": 0.0025310516357421875,
+      "box_residual_unscaled": 633.9265187978745,
+      "cls_residual": 1.9371509552001953e-07,
+      "pass": true,
+      "reason": "ok",
+      "onnx": "spill_robot.onnx",
+      "litert": "spill_robot.tflite"
+    },
+    {
+      "layout": "anchor_4_plus_nc",
+      "imgsz": 640,
+      "box_scale_applied": 640.0,
+      "box_residual_px": 0.00058746337890625,
+      "box_residual_unscaled": 641.6996326446533,
+      "cls_residual": 1.0132789611816406e-06,
+      "pass": true,
+      "reason": "ok",
+      "onnx": "weapon_gunknife_11n.onnx",
+      "litert": "weapon_gunknife_11n.tflite"
+    }
+  ]
+}

package/deploy/detector/bench/twin_parity_contract.py

@@ -0,0 +1,113 @@
+"""The pure-logic half of the twin-parity check — STDLIB ONLY, deliberately.
+
+`verify_litert_twin_parity.py` needs onnxruntime, ai-edge-litert, numpy and
+Pillow, which together are about a gigabyte of wheels and are on no CI runner.
+The `detector-service` step in `ci.yml` runs
+
+    python3 -m unittest discover -s <this package> -p "test_*.py"
+
+with NO pip install, and that constraint is the point rather than an accident:
+`server.py` imports no numpy either, so the whole wire contract runs on a bare
+runner. A test that imported the verifier would drag numpy into discovery and
+error the entire lane before its existing tests ran — which is the same defect
+this file exists to catch, one level up: a check that appears to run and does
+not.
+
+So the decisions a reader has to trust — which layout a graph is, what scale
+that layout implies, and whether a recorded verdict follows from its recorded
+residuals — live here, in stdlib, and are exercised in CI. The arithmetic over
+real tensors lives in the verifier and is a documented manual run.
+"""
+
+from __future__ import annotations
+
+#: Tolerances. Measured across 16 anchor-layout twins on 2026-08-25: the worst
+#: scaled box residual was 0.00588 px and the worst class residual 4.2e-06.
+#: These ceilings sit ~2 orders above the observed worst, so a genuine export
+#: defect fails while fp32 reassociation noise does not.
+BOX_TOL_PX = 0.05
+CLS_TOL = 1e-04
+
+ANCHOR = "anchor_4_plus_nc"
+END2END = "end2end_n_6"
+DETS_LABELS = "rfdetr_dets_labels"
+
+#: Which layouts this bench can COMPARE. `DETS_LABELS` is deliberately absent:
+#: RF-DETR has no LiteRT twin and its own control is `verify_against_reference.py`,
+#: so classifying it correctly and then refusing it by name is the honest
+#: behaviour. Advertising a layout the comparison cannot split would be the
+#: `yolov8_nano` shape in a bench script.
+COMPARABLE_LAYOUTS = frozenset({ANCHOR, END2END})
+
+
+class ParityError(RuntimeError):
+    """The twin does not agree with its ONNX source, or cannot be compared."""
+
+
+def classify_layout(shape, output_names) -> str:
+    """Name the layout from the GRAPH, never from the values.
+
+    `dets`/`labels` is RF-DETR's two-output form. Otherwise a rank-3 tensor is
+    `end2end_n_6` when its LAST axis is 6 (N rows of x1,y1,x2,y2,score,class),
+    and `anchor_4_plus_nc` when the MIDDLE axis is the channel axis. Those two
+    are separated by which axis is the small one — a fact about the graph's
+    declared shape, needing no sample to decide.
+
+    The runtime decoder does not even do this: `session.py` reads the layout
+    from the artifact's DECLARED variant contract, 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. This function is the bench's convenience, and it is
+    deliberately stricter than it needs to be so a new head shape refuses
+    rather than being absorbed.
+    """
+    shape = tuple(int(v) for v in shape)
+    lowered = [str(n).lower() for n in output_names]
+    if "dets" in lowered and "labels" in lowered:
+        return DETS_LABELS
+    if len(shape) != 3:
+        raise ParityError(f"unknown output rank {len(shape)} for shape {shape}")
+    if shape[2] == 6 and shape[1] > 6:
+        return END2END
+    if shape[1] >= 5 and shape[2] > shape[1]:
+        return ANCHOR
+    raise ParityError(f"shape {shape} matches no known detector layout")
+
+
+def box_scale_for(layout: str, imgsz: int) -> float:
+    """The multiplier that puts LiteRT boxes into the ONNX pixel frame.
+
+    Ultralytics wraps a LiteRT export of a `task=detect` / `end2end=False`
+    model in `_NormalizeCoords`, which divides the four BOX channels by (W, H)
+    and leaves the class channels alone. An end2end head is `end2end=True`, so
+    the wrapper never runs and both runtimes emit pixels.
+
+    No layout gets a scale by default. A fall-through to 1.0 would be a guess
+    about an artifact nobody measured, and the wrong guess is silent.
+    """
+    if layout == ANCHOR:
+        return float(imgsz)
+    if layout in (END2END, DETS_LABELS):
+        return 1.0
+    raise ParityError(f"no box scale defined for layout {layout!r}")
+
+
+def verdict(result) -> "tuple[bool, str]":
+    """Does this recorded measurement pass, and if not, which assertion failed."""
+    layout = result["layout"]
+    # The scale must be LOAD-BEARING on the anchor layout. If scaling and not
+    # scaling both pass, the model is not telling us which one is right and the
+    # tolerance is doing no work — that is the 640x bug passing its own check.
+    if layout == ANCHOR and result["box_residual_unscaled"] <= BOX_TOL_PX:
+        return False, (
+            "the imgsz scale changed nothing — an anchor-layout twin whose raw boxes "
+            "already match its ONNX source is not normalised, so the layout is misread"
+        )
+    if result["box_residual_px"] > BOX_TOL_PX:
+        return False, (
+            f"box residual {result['box_residual_px']:.4g} px exceeds {BOX_TOL_PX} "
+            f"under layout {layout} (scale x{result['box_scale_applied']})"
+        )
+    if result["cls_residual"] > CLS_TOL:
+        return False, f"class residual {result['cls_residual']:.4g} exceeds {CLS_TOL}"
+    return True, "ok"

package/deploy/detector/bench/verify_litert_twin_parity.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+"""The control for the SECOND runtime: one model, two runtimes, same tensor.
+
+WHY THIS EXISTS. Every detector we publish ships twice — an ONNX artifact for
+the venue box and a LiteRT twin for the Android screen device. They are exported
+from one `.pt`, so it is tempting to treat the twin as free. It is not, and the
+way it fails is the way this repo's defects always fail: the check runs, passes,
+and measures the wrong thing.
+
+Ultralytics wraps a LiteRT export of a `task=detect` / `end2end=False` model in
+`_NormalizeCoords`, which divides the four box channels by (W, H). The class
+channels are untouched. So a twin whose boxes are 640x wrong still matches its
+ONNX source on output shape, on dtype, on class count, and on every score — the
+four things a parity check naturally asserts. Only the boxes disagree, and only
+if you look at them separately from the scores.
+
+The scale is a property of the LAYOUT, not of the runtime:
+
+  * `anchor_4_plus_nc`  [1, 4+nc, 8400]  LiteRT emits NORMALISED boxes.
+                                          Multiply by imgsz to recover ONNX px.
+  * `end2end_n_6`       [1, 300, 6]      the wrapper is NOT applied; both
+                                          runtimes already emit pixels.
+
+Which means a decoder that scales every LiteRT model is as wrong as one that
+scales none — it just picks a different half of the library to corrupt. See
+`docs/runbooks/cctv-detector-tier.md`.
+
+Detect the layout from the GRAPH — output names and rank — never from the
+magnitude of the values being interpreted. A layout guess that reads the numbers
+it is trying to interpret will always find a self-consistent story: dispatching
+on `shape[1] >= 5` routes a [1, 300, 6] end2end tensor into the anchor branch
+and reports a confident, meaningless class residual of 632.
+
+NOT A CI STEP, deliberately: it needs both runtimes and the artifact pair, which
+together are ~1 GB of wheels. It is a documented manual run, the same shape as
+`verify_against_reference.py` beside it. What CI holds instead is the measured
+result, in `bench/litert-twin-parity.json`, which the publish path reads.
+
+    uv venv /tmp/twin --python 3.11
+    uv pip install --python /tmp/twin/bin/python onnxruntime ai-edge-litert numpy pillow
+    /tmp/twin/bin/python bench/verify_litert_twin_parity.py \\
+        --onnx <exported>.onnx --litert <exported>.tflite
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+import numpy as np
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from twin_parity_contract import (  # noqa: E402  (same directory)
+    ANCHOR,
+    BOX_TOL_PX,
+    CLS_TOL,
+    COMPARABLE_LAYOUTS,
+    DETS_LABELS,
+    END2END,
+    ParityError,
+    box_scale_for,
+    classify_layout,
+    verdict,
+)
+
+
+def split_channels(arr: np.ndarray, layout: str):
+    """Return (boxes, class_or_score) for one output tensor."""
+    if layout == ANCHOR:
+        return arr[:, :4, :], arr[:, 4:, :]
+    if layout == END2END:
+        return arr[..., :4], arr[..., 4:]
+    raise ParityError(f"cannot split channels for layout {layout}")
+
+
+def compare(onnx_out: np.ndarray, litert_out: np.ndarray, layout: str, imgsz: int) -> dict:
+    # Refuse BEFORE touching the tensors. `classify_layout` names RF-DETR
+    # correctly and `box_scale_for` knows its scale, but this bench cannot split
+    # a two-output graph into box and class halves — and RF-DETR has no LiteRT
+    # twin to compare against anyway. Its control is `verify_against_reference.py`
+    # beside this file. Advertising a layout the comparison cannot handle is the
+    # `yolov8_nano` shape in a bench script, so it stops here with the pointer.
+    if layout not in COMPARABLE_LAYOUTS:
+        raise ParityError(
+            f"layout {layout!r} is classified but not comparable by this bench "
+            f"(comparable: {sorted(COMPARABLE_LAYOUTS)}). For {DETS_LABELS} use "
+            "bench/verify_against_reference.py, which is RF-DETR's control."
+        )
+    if onnx_out.shape != litert_out.shape:
+        raise ParityError(f"shape mismatch onnx={onnx_out.shape} litert={litert_out.shape}")
+    a = litert_out.astype(np.float64)
+    b = onnx_out.astype(np.float64)
+    scale = box_scale_for(layout, imgsz)
+    box_l, cls_l = split_channels(a, layout)
+    box_o, cls_o = split_channels(b, layout)
+    return {
+        "layout": layout,
+        "imgsz": imgsz,
+        "box_scale_applied": scale,
+        "box_residual_px": float(np.abs(box_l * scale - box_o).max()),
+        "box_residual_unscaled": float(np.abs(box_l - box_o).max()),
+        "cls_residual": float(np.abs(cls_l - cls_o).max()),
+    }
+
+
+def verdict(result: dict) -> tuple[bool, str]:
+    # The scale must be LOAD-BEARING on the anchor layout. If scaling and not
+    # scaling both pass, the model is not telling us which one is right and the
+    # tolerance is doing no work — that is the 640x bug passing its own check.
+    if result["layout"] == ANCHOR and result["box_residual_unscaled"] <= BOX_TOL_PX:
+        return False, (
+            "the imgsz scale changed nothing — an anchor-layout twin whose raw boxes "
+            "already match its ONNX source is not normalised, so the layout is misread"
+        )
+    if result["box_residual_px"] > BOX_TOL_PX:
+        return False, (
+            f"box residual {result['box_residual_px']:.4g} px exceeds {BOX_TOL_PX} "
+            f"under layout {result['layout']} (scale x{result['box_scale_applied']})"
+        )
+    if result["cls_residual"] > CLS_TOL:
+        return False, f"class residual {result['cls_residual']:.4g} exceeds {CLS_TOL}"
+    return True, "ok"
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--onnx", required=True)
+    ap.add_argument("--litert", required=True)
+    ap.add_argument("--image", help="optional JPEG; random input is used when omitted")
+    ap.add_argument("--seed", type=int, default=1234)
+    ap.add_argument("--json", action="store_true", help="emit the measurement as JSON")
+    args = ap.parse_args()
+
+    import onnxruntime as ort
+    from ai_edge_litert.interpreter import Interpreter
+
+    interp = Interpreter(model_path=args.litert, num_threads=4)
+    interp.allocate_tensors()
+    in_detail = interp.get_input_details()[0]
+    out_details = interp.get_output_details()
+    shape = tuple(int(v) for v in in_detail["shape"])
+
+    # Both runtimes take NCHW here — the LiteRT export of an ultralytics detect
+    # model is NOT NHWC. Transposing "because LiteRT is channels-last" silently
+    # feeds a rotated image and every residual then looks like export noise.
+    if len(shape) != 4 or shape[1] != 3:
+        raise ParityError(f"expected an NCHW [1,3,H,W] input, got {shape}")
+    imgsz = shape[2]
+
+    if args.image:
+        from PIL import Image
+
+        pixels = np.asarray(Image.open(args.image).convert("RGB").resize((imgsz, imgsz)))
+        x = (pixels.astype(np.float32) / 255.0).transpose(2, 0, 1)[None]
+    else:
+        x = np.random.default_rng(args.seed).random(shape).astype(np.float32)
+
+    interp.set_tensor(in_detail["index"], x)
+    interp.invoke()
+    litert_out = interp.get_tensor(out_details[0]["index"])
+
+    sess = ort.InferenceSession(args.onnx, providers=["CPUExecutionProvider"])
+    onnx_names = [o.name for o in sess.get_outputs()]
+    onnx_out = sess.run(None, {sess.get_inputs()[0].name: x})[0]
+
+    layout = classify_layout(tuple(int(v) for v in onnx_out.shape), onnx_names)
+    result = compare(onnx_out, litert_out, layout, imgsz)
+    ok, why = verdict(result)
+    result["pass"] = ok
+    result["reason"] = why
+    result["onnx"] = Path(args.onnx).name
+    result["litert"] = Path(args.litert).name
+
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        print(f"{'PASS' if ok else 'FAIL'}  {result['onnx']}  layout={layout}  {why}")
+        print(f"  box  x{result['box_scale_applied']:g}: {result['box_residual_px']:.4g} px"
+              f"   (unscaled {result['box_residual_unscaled']:.4g})")
+        print(f"  cls           : {result['cls_residual']:.4g}")
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())