@trillboards/edge-sdk 0.2.92 → 0.2.93

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

@@ -0,0 +1,241 @@
+{
+  "_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.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.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": "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())

package/deploy/detector/tests/test_litert_twin_parity_contract.py

@@ -0,0 +1,165 @@
+"""The committed twin-parity measurement must stay a MEASUREMENT.
+
+`bench/litert-twin-parity.json` is the only place the box-scale-per-layout fact
+survives into CI: the verifier that produced it needs both runtimes and ~1 GB of
+wheels, so it is a documented manual run. That makes the JSON the artifact a
+future edit can quietly falsify — flip one `pass` to true, drop the failing row,
+or widen a tolerance, and nothing downstream notices.
+
+STDLIB ONLY, and unittest rather than pytest, because the `detector-service`
+step in `ci.yml` runs `python3 -m unittest discover` with no pip install. An
+earlier draft of this file imported the verifier (and therefore numpy) at module
+scope and would have errored the whole lane before its existing tests ran, while
+also contributing no collected cases of its own — a check that appears to run
+and does not, which is precisely the defect the measurement below is about.
+
+These are pure-logic checks over committed bytes. They do not re-measure; they
+assert the recorded numbers are internally consistent with the code that claims
+to have produced them, which is the part a hand-edit breaks.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import unittest
+from pathlib import Path
+
+BENCH = Path(__file__).resolve().parent.parent / "bench"
+CONTRACT = BENCH / "litert-twin-parity.json"
+
+sys.path.insert(0, str(BENCH))
+
+from twin_parity_contract import (  # noqa: E402
+    ANCHOR,
+    BOX_TOL_PX,
+    CLS_TOL,
+    COMPARABLE_LAYOUTS,
+    DETS_LABELS,
+    END2END,
+    ParityError,
+    box_scale_for,
+    classify_layout,
+    verdict,
+)
+
+#: The artifact whose row-level parity could NOT be established, named so the
+#: assertion below cannot pass by the row being deleted. See the test.
+UNVERIFIED_END2END_ARTIFACT = "queue_supermarket.onnx"
+
+
+class TwinParityContract(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls.contract = json.loads(CONTRACT.read_text())
+        cls.twins = cls.contract["twins"]
+
+    def test_tolerances_match_the_verifier(self):
+        """A widened tolerance in the JSON that the code does not share is a lie."""
+        self.assertEqual(self.contract["tolerances"]["box_residual_px"], BOX_TOL_PX)
+        self.assertEqual(self.contract["tolerances"]["cls_residual"], CLS_TOL)
+
+    def test_every_row_used_the_scale_its_layout_dictates(self):
+        for row in self.twins:
+            with self.subTest(onnx=row["onnx"]):
+                expected = box_scale_for(row["layout"], row["imgsz"])
+                self.assertEqual(
+                    row["box_scale_applied"], expected,
+                    f"{row['onnx']} recorded scale x{row['box_scale_applied']} but layout "
+                    f"{row['layout']} dictates x{expected}",
+                )
+
+    def test_recorded_verdicts_follow_from_recorded_residuals(self):
+        """`pass` must be derivable from the numbers beside it, not asserted."""
+        for row in self.twins:
+            with self.subTest(onnx=row["onnx"]):
+                ok, why = verdict(row)
+                self.assertEqual(
+                    ok, row["pass"],
+                    f"{row['onnx']}: recorded pass={row['pass']} but verdict says {ok} ({why})",
+                )
+
+    def test_the_anchor_scale_is_load_bearing_on_every_anchor_row(self):
+        """An anchor twin whose RAW boxes already match is not normalised.
+
+        This is the 640x bug's signature. If it ever holds, the row passed for
+        the wrong reason and the layout was misread.
+        """
+        anchors = [r for r in self.twins if r["layout"] == ANCHOR]
+        self.assertTrue(anchors, "the contract has no anchor-layout rows to check")
+        for row in anchors:
+            with self.subTest(onnx=row["onnx"]):
+                self.assertGreater(
+                    row["box_residual_unscaled"], BOX_TOL_PX,
+                    f"{row['onnx']}: unscaled residual {row['box_residual_unscaled']} is already "
+                    "inside tolerance, so multiplying by imgsz changed nothing",
+                )
+
+    def test_the_unverified_end2end_row_is_present_and_still_failing(self):
+        """We do NOT get to publish a twin we could not compare.
+
+        `queue_supermarket` returns zero detections above 0.25 on 40 real
+        production frames, so its row-level parity is unknown and it is recorded
+        failing on purpose.
+
+        The PRESENCE assertion is the load-bearing half. Checking only that
+        every `end2end_n_6` row still fails passes vacuously the moment somebody
+        deletes the row — which is exactly the hand-edit this file exists to
+        prevent, and the same "absence read as success" shape as an empty corpus
+        scoring `overallPass: true`. So the row is named.
+        """
+        by_name = {r["onnx"]: r for r in self.twins}
+        self.assertIn(
+            UNVERIFIED_END2END_ARTIFACT, by_name,
+            f"{UNVERIFIED_END2END_ARTIFACT} is missing from the contract. It is the only "
+            f"{END2END} twin and its parity is unverified; removing the row does not make "
+            "it verified. If it was genuinely re-measured on a corpus it fires on, update "
+            "this test with that corpus named.",
+        )
+        row = by_name[UNVERIFIED_END2END_ARTIFACT]
+        self.assertEqual(row["layout"], END2END)
+        self.assertFalse(
+            row["pass"],
+            f"{UNVERIFIED_END2END_ARTIFACT} is recorded passing — see the message above",
+        )
+
+    def test_layout_is_classified_from_the_graph_not_the_values(self):
+        """Shape and output names decide the layout. Nothing else may.
+
+        Dispatching on `shape[1] >= 5` alone routes a [1, 300, 6] end2end tensor
+        into the anchor branch and produces a confident, meaningless class
+        residual. A layout guess that reads the numbers it is interpreting
+        always finds a self-consistent story.
+        """
+        self.assertEqual(classify_layout((1, 300, 6), ["output0"]), END2END)
+        self.assertEqual(classify_layout((1, 14, 8400), ["output0"]), ANCHOR)
+        self.assertEqual(classify_layout((1, 6, 8400), ["output0"]), ANCHOR)
+        self.assertEqual(classify_layout((1, 300, 4), ["dets", "labels"]), DETS_LABELS)
+        with self.assertRaises(ParityError):
+            classify_layout((1, 8400), ["output0"])
+
+    def test_no_layout_gets_a_scale_by_default(self):
+        """An unknown layout must refuse, never fall through to 1.0.
+
+        A silent wrong-layout decode is worse than a refusal: it returns boxes,
+        and boxes that are plausible and wrong are what this file is about.
+        """
+        with self.assertRaises(ParityError):
+            box_scale_for("some_future_layout", 640)
+
+    def test_rfdetr_is_classified_but_not_advertised_as_comparable(self):
+        """Naming a layout is not the same as being able to compare it.
+
+        `classify_layout` recognises RF-DETR's two-output form and
+        `box_scale_for` knows its scale is 1.0, but this bench cannot split a
+        two-output graph into box and class halves, and RF-DETR ships no LiteRT
+        twin. So it must be absent from the comparable set — otherwise the
+        verifier advertises a capability that fails at the point of use.
+        """
+        self.assertNotIn(DETS_LABELS, COMPARABLE_LAYOUTS)
+        self.assertEqual(COMPARABLE_LAYOUTS, frozenset({ANCHOR, END2END}))
+        self.assertEqual(box_scale_for(DETS_LABELS, 640), 1.0)
+
+
+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.92';
+const SDK_VERSION = '0.2.93';
 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.92";
+declare const SDK_VERSION = "0.2.93";
 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.92';
+const SDK_VERSION = '0.2.93';
 exports._SDK_VERSION = SDK_VERSION;
 // ---------------------------------------------------------------------------
 // ANSI helpers (no external deps)

package/package.json

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