@trillboards/edge-sdk 0.2.107 → 0.2.110

package/deploy/detector/bench/regrade_control_selection.py

@@ -0,0 +1,371 @@
+#!/usr/bin/env python3
+"""Re-apply the venue adjudication's own bar with the control-selection fix.
+
+WHY THIS EXISTS
+---------------
+`venue_adjudication.py` chose the control a verdict rests on with
+`argmax(rate_025)` over every set listed for the class. That is a selector with no
+access to the contact-sheet grade, so it reliably picks the set that flatters the
+model. On 2026-08-26 it picked `fire_generic` -- n=5, graded `good_small_n`, whose
+own note reads "n=5 so only a coarse liveness signal" -- over `fire_cctv`, n=39,
+graded `good`, "realistic scale for a venue camera", scored in the same run against
+the same artifact at the same threshold. `fire` and `smoke` were awarded PUBLISH on
+the 5-frame set.
+
+The tool is fixed. Re-running it end to end needs the per-frame score matrices
+(`<alias>.npz` + `combo.json`) from the eval box, which are not committed. This
+re-applies the SAME bar to the numbers the artifact already carries, so the
+corrected verdict is derivable from what is in the repo -- and, crucially, marks
+each capability `proven` or `needs_remeasure` rather than pretending the elided
+rows are known.
+
+WHAT IT CANNOT DO, AND SAYS SO
+------------------------------
+`venue_adjudication.py` elides `per_control` for candidates ranked 5+ that carry no
+shipped bytes. For those rows only the WINNING set's rate survives. Where the
+winning set was liveness-only, that candidate's rateable-control rate is unknown
+and the capability is reported `needs_remeasure` with the candidate named. An
+unknown is not a pass and it is not a fail; it is the reason to re-run.
+
+    python3 regrade_control_selection.py \
+        --adjudication trillboard-api/scripts/ai/eval-baselines/venue-adjudication-2026-08-26.json \
+        --control-quality trillboard-api/scripts/ai/eval-baselines/positive-control-quality-2026-08-25.json \
+        --out trillboard-api/scripts/ai/eval-baselines/venue-adjudication-control-regrade-2026-08-26.json
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+
+#: Grades whose own note says the set cannot rate a class. Kept in step with
+#: `venue_adjudication.py::LIVENESS_ONLY_GRADES`; the test pins them equal.
+LIVENESS_ONLY_GRADES = ("good_small_n", "weak")
+UNUSABLE_GRADES = ("DISCARDED", "POOR", "CONTAMINATED")
+
+#: What a capability becomes when the PUBLISH is provably withdrawn but what
+#: replaces it is not. NOT a verdict a model may ship on, and NOT a failure: the
+#: elided rows could still clear the bar, and writing "NO MODEL CLEARS BAR" over
+#: them would be the same mistake in the other direction -- a definitive claim
+#: standing on evidence that was never committed.
+UNRESOLVED = "UNRESOLVED PENDING REMEASURE"
+
+#: Priors that an unknown may hold open. A PUBLISH because it is exactly what this
+#: tool exists to withdraw; `UNRESOLVED` because this tool writes it, and a run
+#: over its own output must not harden "not known" into "known bad".
+PRESERVE_ON_BLOCKING = ("PUBLISH", UNRESOLVED)
+
+
+def rateable_controls(per_control: dict, ctlq: dict) -> dict:
+    """The controls that may carry a verdict: graded, usable, not liveness-only."""
+    out = {}
+    for name, row in (per_control or {}).items():
+        grade = (ctlq.get(name) or {}).get("grade")
+        if grade in LIVENESS_ONLY_GRADES or grade in UNUSABLE_GRADES:
+            continue
+        out[name] = dict(row, grade=grade)
+    return out
+
+
+def regrade_capability(cap: dict, ctlq: dict, bar: dict) -> dict:
+    """Re-apply the bar to one capability using only rateable controls."""
+    recall_bar = bar["recall_retention"]
+    off_bar = bar["off_target_mean"]
+    prior = cap["decision"].get("decision")
+
+    # `decide()` resolves two branches BEFORE it ever looks at a control, and both
+    # are properties of the negative set. Re-deriving them here would only
+    # reproduce them from less information, and getting them subtly wrong is how a
+    # regrade starts reporting movement it did not cause -- the first run of this
+    # tool "moved" eight capabilities that have no control involved at all.
+    if not cap["candidates"] or prior in ("NO CANDIDATE", "NOT SCREENABLE HERE"):
+        return {
+            "capability": cap["capability"],
+            "prior_decision": prior,
+            "regraded_decision": prior,
+            "changed": False,
+            "status": "not_affected",
+            "why": "resolved before any control is read: %s" % (prior,),
+        }
+
+    rows, unknown = [], []
+    for cand in cap["candidates"]:
+        elided = "_elided" in (cand.get("by_bucket") or {})
+        rate = rateable_controls(cand.get("per_control"), ctlq)
+        if not rate:
+            # No per-control detail survived the elision. If the set this row was
+            # decided on is itself rateable, the surviving number IS the rateable
+            # number and the row is knowable; otherwise it is not.
+            best = cand.get("best_control")
+            bg = (ctlq.get(best) or {}).get("grade") if best else None
+            if best and bg not in LIVENESS_ONLY_GRADES and bg not in UNUSABLE_GRADES:
+                rows.append({
+                    "model": cand["model"], "class": cand["class"],
+                    "control": best, "control_n": cand.get("control_n"),
+                    "grade": bg,
+                    "rate_at_quiet_t": cand.get("control_rate_at_quiet_t"),
+                    "rate_025": cand.get("control_rate_025"),
+                    "off_target_mean": cand.get("off_target_mean"),
+                    "quiet_t": cand.get("quiet_t"),
+                    "n_valid_negatives": cand.get("n_valid_negatives"),
+                    "source": "winning set was already rateable",
+                })
+            else:
+                unknown.append({
+                    "model": cand["model"], "class": cand["class"],
+                    "decided_on": best, "grade": bg,
+                    "why_unknown": ("per_control elided for this rank and the set it was "
+                                    "decided on cannot rate a class, so its rateable-control "
+                                    "rate was never committed"),
+                    "elided": elided,
+                })
+            continue
+        # argmax(rate_025) among the rateable, exactly as the fixed tool does.
+        name = max(rate, key=lambda k: (rate[k]["rate_025"] or 0))
+        row = rate[name]
+        rows.append({
+            "model": cand["model"], "class": cand["class"],
+            "control": name, "control_n": row["n"], "grade": row["grade"],
+            "rate_at_quiet_t": row["rate_at_quiet_t"], "rate_025": row["rate_025"],
+            "off_target_mean": cand.get("off_target_mean"),
+            "quiet_t": cand.get("quiet_t"),
+            "n_valid_negatives": cand.get("n_valid_negatives"),
+            "also_scored": {k: {"n": v["n"], "grade": (ctlq.get(k) or {}).get("grade"),
+                                "rate_at_quiet_t": v["rate_at_quiet_t"]}
+                            for k, v in (cand.get("per_control") or {}).items() if k != name},
+            "source": "recomputed from committed per_control",
+        })
+
+    live = [r for r in rows if (r["rate_025"] or 0) > 0]
+    retained = [r for r in live if (r["rate_at_quiet_t"] or 0) >= recall_bar]
+    ok = [r for r in retained
+          if r["off_target_mean"] is not None and r["off_target_mean"] <= off_bar]
+
+    if ok:
+        # The artifact's own ordering is preserved: candidates arrive sorted.
+        win = ok[0]
+        verdict = "PUBLISH"
+        why = ("clears the bar on %s (n=%d, grade %s): keeps %.1f%% at conf %s"
+               % (win["control"], win["control_n"], win["grade"],
+                  100 * (win["rate_at_quiet_t"] or 0), win["quiet_t"]))
+    elif live:
+        best = max(live, key=lambda r: (r["rate_at_quiet_t"] or 0))
+        verdict = "NO MODEL CLEARS BAR"
+        why = ("no candidate keeps >=%.0f%% of a control that can rate a class. Best is "
+               "%s / '%s' at %.1f%% of %s (n=%d, grade %s)."
+               % (100 * recall_bar, best["model"], best["class"],
+                  100 * (best["rate_at_quiet_t"] or 0), best["control"],
+                  best["control_n"], best["grade"]))
+        win = None
+    else:
+        verdict, why, win = "UNINFORMATIVE", "no candidate fires on a rateable control", None
+
+    # An unknown row can only ever ADD a passing candidate, so it can overturn a
+    # failing verdict and can never overturn a PUBLISH.
+    blocking = unknown if verdict != "PUBLISH" else []
+
+    # ...and a verdict an unknown could overturn must not be stated as if it could
+    # not. Withdrawing the PUBLISH is CERTAIN -- it rested on a set that cannot
+    # rate a class, and no re-measurement changes that. Replacing it with a
+    # definitive failure is NOT certain, because an elided candidate could still
+    # clear the bar. Two different claims; only the first is proved here, and
+    # asserting the second would be the same error in the other direction.
+    #
+    # Gated on the PRIOR. Where the prior was already a MEASURED failure, the
+    # original run reached it with MORE controls and better data than this tool
+    # has for the elided rows, so overwriting it with `UNRESOLVED` would be this
+    # tool asserting its own blindness over a measurement. Those rows still carry
+    # `status: needs_remeasure`; their verdict is left alone.
+    #
+    # `UNRESOLVED` is in the set because THIS TOOL WRITES IT. Without it, running
+    # `--apply` twice would see `prior == UNRESOLVED`, skip this branch, and
+    # overwrite its own careful "not known" with a definitive `NO MODEL CLEARS
+    # BAR` -- the exact claim the first run refused to make, on the same
+    # evidence. The guard would not catch it either: it audits PUBLISH rows only.
+    # `--selftest` pins the idempotence.
+    if blocking and verdict == "NO MODEL CLEARS BAR" and prior in PRESERVE_ON_BLOCKING:
+        why = ("the prior verdict is WITHDRAWN -- it rested on a control that cannot rate a "
+               "class, which no re-measurement changes. What REPLACES it is not yet known: "
+               + why
+               + (" %d candidate(s) had their rateable-control rate elided and could still "
+                  "clear the bar (%s). Re-run venue_adjudication.py against the score "
+                  "matrices to settle it."
+                  % (len(blocking), ", ".join("%s/%s" % (b["model"], b["class"])
+                                              for b in blocking))))
+        verdict = UNRESOLVED
+
+    return {
+        "capability": cap["capability"],
+        "prior_decision": prior,
+        "prior_control": cap["decision"].get("control"),
+        "prior_control_n": cap["decision"].get("control_n"),
+        "prior_control_grade": (ctlq.get(cap["decision"].get("control")) or {}).get("grade"),
+        "prior_events_lost": (cap["decision"].get("gate") or {}).get("events_lost"),
+        "regraded_decision": verdict,
+        "changed": bool(prior and prior != verdict),
+        "status": "needs_remeasure" if blocking else "proven",
+        "why": why,
+        "winner": win,
+        "candidates_regraded": len(rows),
+        "candidates_unknown": blocking,
+    }
+
+
+def _selftest() -> None:
+    """Pin the two things a reader cannot see by reading the ladder.
+
+    1. IDEMPOTENCE. `--apply` writes `UNRESOLVED` into the artifact it reads. A
+       second run must reproduce it, not harden it into a failure.
+    2. A MEASURED failure is left alone. A prior that was already
+       `NO MODEL CLEARS BAR` came from a run with more controls than this tool
+       holds for an elided row, and must not be softened to `UNRESOLVED` either.
+    """
+    ctlq = {"big": {"grade": "good"}, "tiny": {"grade": "good_small_n"}}
+    bar = {"recall_retention": 0.5, "off_target_mean": 0.1}
+
+    def cap(prior):
+        return {
+            "capability": "fire",
+            "decision": {"decision": prior, "control": "tiny", "control_n": 5},
+            "candidates": [
+                {   # a candidate that fails on the rateable set
+                    "model": "m1", "class": "fire", "quiet_t": 0.25,
+                    "off_target_mean": 0.0, "n_valid_negatives": 100,
+                    "by_bucket": {}, "best_control": "big", "control_n": 9,
+                    "control_rate_025": 0.4, "control_rate_at_quiet_t": 0.4,
+                    "per_control": {"big": {"n": 9, "rate_025": 0.4, "rate_at_quiet_t": 0.4},
+                                    "tiny": {"n": 5, "rate_025": 0.9, "rate_at_quiet_t": 0.9}},
+                },
+                {   # ...and one whose rateable rate was elided
+                    "model": "m2", "class": "fire", "quiet_t": 0.25,
+                    "off_target_mean": 0.0, "n_valid_negatives": 100,
+                    "by_bucket": {"_elided": "summary row"},
+                    "best_control": "tiny", "control_n": 5,
+                    "control_rate_025": 0.9, "control_rate_at_quiet_t": 0.9,
+                    "per_control": {},
+                },
+            ],
+        }
+
+    first = regrade_capability(cap("PUBLISH"), ctlq, bar)
+    assert first["regraded_decision"] == UNRESOLVED, first["regraded_decision"]
+    assert first["candidates_unknown"], "the elided row must be reported"
+
+    second = regrade_capability(cap(first["regraded_decision"]), ctlq, bar)
+    assert second["regraded_decision"] == UNRESOLVED, (
+        "re-running over this tool's own output hardened an unknown into %r"
+        % second["regraded_decision"])
+    assert second["changed"] is False, "a settled UNRESOLVED must not read as changed"
+
+    measured = regrade_capability(cap("NO MODEL CLEARS BAR"), ctlq, bar)
+    assert measured["regraded_decision"] == "NO MODEL CLEARS BAR", measured["regraded_decision"]
+
+    print("selftest OK: idempotent on UNRESOLVED; a measured failure is left alone")
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    if "--selftest" in __import__("sys").argv[1:]:
+        _selftest()
+        return
+    ap.add_argument("--adjudication", required=True)
+    ap.add_argument("--control-quality", required=True)
+    ap.add_argument("--out", required=True)
+    ap.add_argument("--apply", action="store_true",
+                    help="also write the corrected verdict back into --adjudication. The "
+                         "adjudication is the record; leaving a verdict in it that its own "
+                         "numbers refute is a second source of truth, not a safer one.")
+    args = ap.parse_args()
+
+    adj = json.load(open(args.adjudication))
+    ctlq = json.load(open(args.control_quality))
+    bar = adj["bar"]
+
+    rows = [regrade_capability(c, ctlq, bar) for c in adj["capabilities"]]
+    changed = [r for r in rows if r["changed"]]
+
+    # The regrade artifact is a record OF A TRANSITION. Once `--apply` has run, the
+    # adjudication no longer holds the verdict that moved, so a second run reads
+    # nothing to change and would write an empty `changed_list` over the record of
+    # what did. The adjudication itself is idempotent (proved by `--selftest` and
+    # by re-running `--apply`, which leaves it byte-identical); this file is not,
+    # and erasing it silently would leave the corrected artifact with nothing
+    # beside it saying what it was corrected FROM.
+    if not changed and os.path.exists(args.out):
+        try:
+            prev = json.load(open(args.out))
+        except (OSError, ValueError):
+            prev = {}
+        if (prev.get("summary") or {}).get("changed"):
+            raise SystemExit(
+                "refusing to overwrite %s: it records %d capability transition(s) and this "
+                "run found none, because the adjudication it read has ALREADY been corrected. "
+                "That is the expected result of re-running, not a reason to erase the record. "
+                "Point --out somewhere else, or re-run against an uncorrected adjudication."
+                % (args.out, (prev["summary"] or {})["changed"]))
+
+    json.dump({
+        "schema": "trillboards.venue-adjudication-control-regrade/1",
+        "regrades": adj["schema"] + " @ " + adj["negative_set"],
+        "_what": "the SAME bar, re-applied with the control-selection fix: a verdict may "
+                 "only rest on a control whose contact-sheet grade can rate a class.",
+        "_not_a_re_run": "the per-frame scores are unchanged and are NOT re-derived here. "
+                         "This re-reads the numbers the adjudication already committed. A "
+                         "capability marked `needs_remeasure` has a candidate whose "
+                         "rateable-control rate was elided and must come from a re-run.",
+        "liveness_only_grades": list(LIVENESS_ONLY_GRADES),
+        "unusable_grades": list(UNUSABLE_GRADES),
+        "bar": bar,
+        "summary": {
+            "capabilities": len(rows),
+            "changed": len(changed),
+            "changed_list": [{"capability": r["capability"],
+                              "was": r["prior_decision"], "now": r["regraded_decision"],
+                              "status": r["status"]} for r in changed],
+        },
+        "capabilities": rows,
+    }, open(args.out, "w"), indent=1)
+
+    if args.apply and changed:
+        by_cap = {r["capability"]: r for r in changed}
+        for cap in adj["capabilities"]:
+            r = by_cap.get(cap["capability"])
+            if not r:
+                continue
+            was = dict(cap["decision"])
+            cap["decision"] = {
+                "decision": r["regraded_decision"],
+                "why": r["why"],
+                # The gate is a promise computed from a recall this verdict no
+                # longer accepts. Keeping it would leave an events-lost figure in
+                # the file with nothing behind it.
+                "gate": None,
+                "corrected": {
+                    "on": "2026-08-26",
+                    "by": "deploy/detector/bench/regrade_control_selection.py --apply",
+                    "was": was,
+                    "ships": False,
+                    "why_corrected": (
+                        "the verdict rested on `%s` (n=%s, grade %s), a set whose own "
+                        "contact-sheet note says it can only show liveness. Re-applying "
+                        "this run's OWN bar to the controls that can rate a class "
+                        "overturns it." % (was.get("control"), was.get("control_n"),
+                                           r.get("prior_control_grade"))),
+                    "needs_remeasure": r["candidates_unknown"],
+                    "regrade_artifact": args.out,
+                },
+            }
+            cap["changed"] = bool(cap.get("prior_decision_taxi_negatives")
+                                  and cap["prior_decision_taxi_negatives"]
+                                  != r["regraded_decision"])
+        json.dump(adj, open(args.adjudication, "w"), indent=1)
+
+    print(json.dumps({"capabilities": len(rows), "changed": len(changed),
+                      "applied": bool(args.apply and changed),
+                      "changed_list": [(r["capability"], r["prior_decision"],
+                                        r["regraded_decision"], r["status"])
+                                       for r in changed]}, indent=1))
+
+
+if __name__ == "__main__":
+    main()

package/deploy/detector/bench/venue_adjudication.py

@@ -15,8 +15,8 @@ industrial logistics yard, a hospital hand-wash basin, a big-box retail aisle an
 an office/lab room. The positive controls are unchanged -- only the negative half
 of every number moves, which is exactly the variable under test.
 
-THE TWO RULES THIS FILE ENFORCES
---------------------------------
+THE THREE RULES THIS FILE ENFORCES
+---------------------------------
 1. "Quiet" is UNEVENTFUL, not EMPTY. The industrial footage contains people
    working and a running forklift. A forklift frame is a POSITIVE for forklift and
    a negative only for other classes, so validity is decided PER CLASS PER BUCKET
@@ -31,6 +31,21 @@ THE TWO RULES THIS FILE ENFORCES
    at 0.22 s between frames -- `source_span_hours` in the composition is what
    stops a frame count being read as an independence claim.
 
+3. A VERDICT RESTS ON A CONTROL THAT CAN RATE A CLASS. Every positive control
+   carries a contact-sheet grade, and two of those grades -- `good_small_n` and
+   `weak` -- exist precisely to say "this set can show the model is alive, it
+   cannot tell you how often it is right". Those sets are still scored and still
+   reported; what they may not do is decide. The selector used to be
+   `argmax(rate_at_conf_0.25)` over every control, which has no access to the
+   grade and therefore reliably picks whichever set flatters the model -- and the
+   smallest set flatters most, because five frames cannot disagree with much.
+   On 2026-08-26 that awarded `fire` and `smoke` PUBLISH on `fire_generic` (n=5,
+   `good_small_n`, "n=5 so only a coarse liveness signal") while `fire_cctv`
+   (n=39, `good`, "realistic scale for a venue camera") was scored in the same
+   run and said 41.0% and 46.2% -- both under this file's own 50% recall floor.
+   Note that `RECALL_RETENTION_BAR` is an ABSOLUTE floor on recall at the
+   operating threshold despite its name; it is not a ratio.
+
 SCORED AS A CASCADE GATE, NOT A DETECTOR. The ranking inverts: what matters is
 calls removed against events lost at the production empty-frame prior, not raw
 precision. `cctv-detector-tier.md` is the authority on why.
@@ -98,7 +113,13 @@ CAPS = {
 # 'PROD' is dropped: it meant the 1,500 rideshare frames, and a positive control
 # drawn from the domain under test is exactly the confound this run removes.
 CLASS_CONTROL = {
-    "fire": ["fire_cctv", "fire_generic"], "smoke": ["fire_cctv", "fire_generic"],
+    # `fire_firesense` (72 frames / 9 scenes) and `smoke_firesense` (78 / 10) are the
+    # sets that can rate these classes; `fire_cctv` (39) is kept because it is the
+    # only other in-domain CCTV set, and `fire_generic` (5, `good_small_n`) is kept
+    # so its number stays VISIBLE in `per_control` — it is the set that carried
+    # both PUBLISH verdicts on 2026-08-26 and the reader should see what it said.
+    "fire": ["fire_firesense", "fire_cctv", "fire_generic"],
+    "smoke": ["smoke_firesense", "fire_cctv", "fire_generic"],
     "helmet": ["helmet", "n_heavy"], "hardhat": ["helmet", "n_heavy"], "hard_hat": ["helmet", "n_heavy"],
     "hat": ["helmet", "ppe_full"],
     "vest": ["helmet", "n_heavy", "n_cone", "ppe_full"], "safety vest": ["helmet", "n_heavy", "n_cone", "ppe_full"],
@@ -131,6 +152,63 @@ CLASS_CONTROL = {
     "cigarette": ["n_smoking"], "Cigarette": ["n_smoking"], "smoking": ["n_smoking"],
 }
 
+#: Contact-sheet grades that forbid CITING a set at all. `wc_spill` is graded
+#: CONTAMINATED -- "search pulled 'oil spill' -- an overturned truck -- a cathedral
+#: corridor, building exteriors and abstract cream textures" -- and citing it would
+#: have given `spill` a recall number off a set that mostly does not contain one.
+UNUSABLE_GRADES = ("DISCARDED", "POOR", "CONTAMINATED")
+
+#: Grades whose OWN note says the set cannot rate a class. These are not unusable:
+#: they are real frames, they are scored, and every one of them is reported in
+#: `per_control`. What they may not be is the set a PUBLISH rests on.
+#:
+#: MODULE SCOPE ON PURPOSE. `check-positive-control-grade.js` refuses the same
+#: grades and its fixture test reads this tuple out of this file, so a guard and a
+#: tool that disagreed would let a file through that the other would never emit.
+#: While these lived inside `main()` nothing could assert on them from either side.
+LIVENESS_ONLY_GRADES = ("good_small_n", "weak")
+
+#: Where the dated grade files live, relative to the repo root. Derived from this
+#: file's own location so the tool has no cwd dependency.
+CONTROL_QUALITY_DIR = os.path.join(
+    os.path.dirname(os.path.abspath(__file__)),
+    *([os.pardir] * 6), "trillboard-api", "scripts", "ai", "eval-baselines")
+
+
+def discover_control_quality(directory: str = CONTROL_QUALITY_DIR) -> list:
+    """Every `positive-control-quality-*.json`, sorted, so a run cannot read a subset.
+
+    `check-positive-control-grade.js` merges all of them. If this tool read fewer,
+    the two would disagree about which sets are graded -- and the disagreement is
+    not symmetric: an ungraded set is absent from `liveness_only` AND from
+    `unusable`, so it silently becomes eligible to carry a verdict.
+    """
+    if not os.path.isdir(directory):
+        return []
+    return sorted(os.path.join(directory, n) for n in os.listdir(directory)
+                  if n.startswith("positive-control-quality-") and n.endswith(".json"))
+
+
+def assert_every_control_is_graded(pos_sets, ctlq) -> None:
+    """Refuse to adjudicate on a control set that has no contact-sheet grade.
+
+    The committed-artifact guard catches this downstream, but by then a wrong
+    number has been produced, written and possibly quoted. A set nobody has looked
+    at is not evidence, and the failure mode is silent in the flattering
+    direction: ungraded means not-liveness-only and not-unusable, which means
+    eligible to be `best_control`.
+    """
+    graded = set(ctlq)
+    used = {name for names in CLASS_CONTROL_N.values() for name in names}
+    missing = sorted(s for s in pos_sets if s in used and s not in graded)
+    if missing:
+        raise SystemExit(
+            "ungraded positive control(s) scored in this run: %s. Grade them on a contact "
+            "sheet and add them to a positive-control-quality-*.json, or drop them from "
+            "CLASS_CONTROL. An ungraded set is neither `unusable` nor `liveness_only`, so it "
+            "would be treated as able to rate a class." % ", ".join(missing))
+
+
 def normalise_class(name: str) -> str:
     """`labels.py::normalize_class_name`: lower, and `-`/`_` folded to space.
 
@@ -310,9 +388,21 @@ def main() -> None:
     ap.add_argument("--combo", required=True, help="combo.json written by vm_prep2.py")
     ap.add_argument("--grading", required=True, help="venue absence grading json")
     ap.add_argument("--plan", required=True, help="scripts/sensing/quiet-hour-fleet-plan.json")
-    ap.add_argument("--control-quality",
-                    default="trillboard-api/scripts/ai/eval-baselines/positive-control-quality-2026-08-25.json",
-                    help="contact-sheet grades for the positive control sets; DISCARDED/POOR/CONTAMINATED are refused")
+    ap.add_argument("--control-quality", nargs="+", default=None,
+                    help="positive-control-quality-*.json. DEFAULTS to every such file in "
+                         "trillboard-api/scripts/ai/eval-baselines/, sorted, merged with "
+                         "later files winning. The grades live in DATED files -- the "
+                         "2026-08-25 record is pinned by the score cards that cite it, so a "
+                         "set graded later lands in a new file rather than editing that one "
+                         "-- and a run that read only some of them would give an UNGRADED "
+                         "control the benefit of the doubt: `liveness_only` and `unusable` "
+                         "are both built by membership, so a set with no grade falls through "
+                         "both and can carry a PUBLISH. `discover_control_quality` is "
+                         "therefore the default and an explicit list is an override for "
+                         "replaying an old run, not the normal path. Either way "
+                         "`assert_every_control_is_graded` refuses the run rather than "
+                         "adjudicating on a set nobody looked at."
+    )
     ap.add_argument("--out", required=True)
     ap.add_argument("--markdown", help="also write the runbook table here")
     args = ap.parse_args()
@@ -320,7 +410,16 @@ def main() -> None:
     combo = json.load(open(args.combo))
     grading = json.load(open(args.grading))
     plan = json.load(open(args.plan))
-    ctlq = json.load(open(args.control_quality))
+    quality_paths = (discover_control_quality() if args.control_quality is None
+                     else list(args.control_quality))
+    if not quality_paths:
+        raise SystemExit("no positive-control-quality-*.json found; a run with no grades "
+                         "cannot tell a control that can rate a class from one that cannot")
+    ctlq = {}
+    for _q in quality_paths:
+        for _k, _v in json.load(open(_q)).items():
+            if isinstance(_v, dict) and isinstance(_v.get("grade"), str):
+                ctlq[_k] = _v
     index = json.load(open(os.path.join(args.out_dir, "_index.json")))
 
     meta = combo["meta"]
@@ -328,6 +427,7 @@ def main() -> None:
     sets = np.array([m["set"] for m in meta])
     is_neg = sets == "venue_src"
     pos_sets = sorted({m["pos_set"] for m in meta if m.get("pos_set")})
+    assert_every_control_is_graded(pos_sets, ctlq)
 
     # Positive-control sets whose contact-sheet grade forbids citing them.
     # CONTAMINATED belongs here and was missed on the first pass: `wc_spill` is
@@ -336,10 +436,26 @@ def main() -> None:
     # citing it would have given `spill` a recall number off a set that mostly
     # does not contain a spill. Read the grades, do not enumerate the bad ones
     # from memory.
-    UNUSABLE_GRADES = ("DISCARDED", "POOR", "CONTAMINATED")
     unusable = {k for k, v in ctlq.items()
                 if isinstance(v, dict) and v.get("grade") in UNUSABLE_GRADES}
 
+    # Grades whose OWN note says the set cannot rate a class. These are not
+    # unusable -- they are real frames, they are scored, and every one of them is
+    # reported in `per_control`. What they may not be is the set a PUBLISH rests
+    # on, which is a different question from whether they may be cited at all.
+    #
+    # This exists because `fire` and `smoke` were awarded PUBLISH on `fire_generic`,
+    # n=5, graded `good_small_n` with the note "n=5 so only a coarse liveness
+    # signal" -- while `fire_cctv`, n=39, graded `good`, "realistic scale for a
+    # venue camera", was scored in the same run and says something else. The
+    # selector was `argmax(rate_025)` over every control, so the SMALLEST and most
+    # flattering set won and its n became the `control_n` the verdict quoted. A
+    # selector that cannot see the grade will keep choosing the set that flatters
+    # it; the grade file was already loaded three lines up and only consulted for
+    # the DISCARDED list.
+    liveness_only = {k for k, v in ctlq.items()
+                     if isinstance(v, dict) and v.get("grade") in LIVENESS_ONLY_GRADES}
+
     # ---- composition, stated rather than assumed ----------------------------
     # `source_span_hours` is what keeps the frame count honest. 480 industrial
     # frames spread over 10.77 h are 81 s apart and independent; 400 retail frames
@@ -566,7 +682,14 @@ def main() -> None:
                     continue
                 r25 = float((col[m] >= 0.25).mean())
                 rqt = float((col[m] >= quiet_t).mean()) if quiet_t is not None else None
-                per_ctl[s] = {"n": int(m.sum()), "rate_025": r25, "rate_at_quiet_t": rqt}
+                per_ctl[s] = {"n": int(m.sum()), "rate_025": r25, "rate_at_quiet_t": rqt,
+                              "grade": (ctlq.get(s) or {}).get("grade"),
+                              "can_rate_a_class": s not in liveness_only}
+                # The set a verdict rests on must be one that can rate a class.
+                # A liveness-only set still appears above, with its n and its
+                # grade, so the reader sees what it said and why it did not decide.
+                if s in liveness_only:
+                    continue
                 if best_rate is None or r25 > best_rate:
                     best_ctl, best_rate, best_at_qt = s, r25, rqt
 
@@ -621,7 +744,13 @@ def main() -> None:
                 "quiet_fire_by_bucket": quiet_by_bucket,
                 "best_control": best_ctl, "control_n": (per_ctl.get(best_ctl) or {}).get("n"),
                 "control_rate_025": best_rate, "control_rate_at_quiet_t": best_at_qt,
+                "control_grade": (ctlq.get(best_ctl) or {}).get("grade") if best_ctl else None,
                 "per_control": per_ctl,
+                # Scored, reported, and NOT allowed to decide. Named here so a
+                # reader can see that a smaller set said something friendlier and
+                # why it was not the one quoted.
+                "liveness_only_controls": sorted(k for k in per_ctl
+                                                 if not per_ctl[k]["can_rate_a_class"]),
                 "off_target_mean": off_mean,
                 "off_target_n_sets": len(off),
                 "off_target_worst": ({"set": off_worst[0], "rate": off_worst[1]} if off_worst else None),
@@ -666,9 +795,25 @@ def main() -> None:
         "bar": {
             "quiet_max_fire": QUIET_MAX_FIRE,
             "recall_retention": RECALL_RETENTION_BAR,
+            "recall_retention_is": "an ABSOLUTE floor on recall at the operating "
+                                   "threshold, not a ratio against the 0.25 rate. A "
+                                   "candidate keeping 41% of its control at quiet_t "
+                                   "fails it however flat its own curve is.",
             "off_target_mean": OFF_TARGET_BAR,
             "why": "identical to the 2026-08-25 screen so the only variable is the negative set",
         },
+        "control_selection": {
+            "rule": "the control a verdict rests on must be one whose contact-sheet "
+                    "grade can rate a class; %s are scored and reported but may not "
+                    "decide" % (", ".join(LIVENESS_ONLY_GRADES),),
+            "liveness_only_grades": list(LIVENESS_ONLY_GRADES),
+            "unusable_grades": list(UNUSABLE_GRADES),
+            "among_rateable": "argmax(rate_at_conf_0.25), unchanged",
+            "read_per_control_not_control_n": "`control_n` is ONE set's n. Every set "
+                                              "scored for that class is in `per_control` "
+                                              "with its own n, grade and rate. Never quote "
+                                              "`control_n` without them.",
+        },
         "composition": comp,
         "export_reproducibility": repro,
         "venue_empty_frame_prior": venue_prior,
@@ -729,6 +874,24 @@ def _short(v: str) -> str:
             "NO MODEL CLEARS BAR": "NO MODEL CLEARS BAR"}.get(v, v)
 
 
+def _other_controls_clause(win: dict) -> str:
+    """Every OTHER control this artifact was scored against, in the `why` string.
+
+    The verdict line is what gets pasted into a deck. If the only number in it is
+    the winning set's, the reader has no way to know a bigger set was scored and
+    disagreed -- which is exactly how `fire` was quoted as "60% on 5 frames" while
+    a 39-frame in-domain set in the same run said 41%.
+    """
+    others = {k: v for k, v in (win.get("per_control") or {}).items()
+              if k != win.get("best_control")}
+    if not others:
+        return ""
+    parts = ["%s %.0f%% (n=%d, %s)" % (k, 100 * (v["rate_at_quiet_t"] or 0), v["n"],
+                                       "rateable" if v["can_rate_a_class"] else "liveness-only")
+             for k, v in sorted(others.items(), key=lambda kv: -kv[1]["n"])]
+    return "; the same artifact at that threshold keeps " + ", ".join(parts)
+
+
 def decide(cap: str, cands: list) -> dict:
     """PUBLISH / NO MODEL CLEARS BAR / NOT SCREENABLE, with the reason.
 
@@ -776,13 +939,19 @@ def decide(cap: str, cands: list) -> dict:
     return {"decision": "PUBLISH", "model": win["model"], "class": win["class"],
             "operating_conf": win["quiet_t"],
             "control": win["best_control"], "control_n": win["control_n"],
+            "control_grade": win.get("control_grade"),
+            "all_controls": {k: {"n": v["n"], "grade": v["grade"],
+                                 "rate_at_quiet_t": v["rate_at_quiet_t"],
+                                 "can_rate_a_class": v["can_rate_a_class"]}
+                             for k, v in (win.get("per_control") or {}).items()},
             "n_valid_negatives": win["n_valid_negatives"],
             "gate": win["gate"],
-            "why": "fires on %s (%s frames) at %.0f%%, keeps %.0f%% of that at conf %.3f, "
-                   "where it fires on <1%% of %d hand-declared venue negatives"
-                   % (win["best_control"], win["control_n"], 100 * (win["control_rate_025"] or 0),
+            "why": "fires on %s (%s frames, grade %s) at %.0f%%, keeps %.0f%% of that at "
+                   "conf %.3f, where it fires on <1%% of %d hand-declared venue negatives%s"
+                   % (win["best_control"], win["control_n"], win.get("control_grade"),
+                      100 * (win["control_rate_025"] or 0),
                       100 * (win["control_rate_at_quiet_t"] or 0), win["quiet_t"] or 0,
-                      win["n_valid_negatives"]),
+                      win["n_valid_negatives"], _other_controls_clause(win)),
             "runner_up": ok[1]["model"] if len(ok) > 1 else None}
 
 

package/deploy/detector/tests/test_regrade_control_selection.py

@@ -0,0 +1,120 @@
+"""A regrade that writes `UNRESOLVED` must reproduce it, not harden it.
+
+`regrade_control_selection.py --apply` writes its verdict back into the
+adjudication it read. That makes the tool its own input, and the branch that
+emits `UNRESOLVED PENDING REMEASURE` was originally gated on
+`prior == "PUBLISH"` — so a second run saw `prior == "UNRESOLVED …"`, took the
+gate as false, and replaced a careful "we do not know" with a definitive
+`NO MODEL CLEARS BAR`, on exactly the same evidence the first run had refused to
+conclude from. Nothing downstream would have caught it: the `positive-control-grade`
+guard audits PUBLISH rows only, and both states are non-PUBLISH.
+
+The other half is the mirror error. A prior that was ALREADY a measured
+`NO MODEL CLEARS BAR` came out of a run that scored more controls than this tool
+holds for an elided row, so softening it to `UNRESOLVED` would be the tool
+asserting its own blindness over a measurement.
+
+STDLIB ONLY — the detector CI lane runs `python3 -m unittest discover` with no
+pip install, and `regrade_control_selection.py` imports nothing but the stdlib
+for that reason.
+"""
+
+from __future__ import annotations
+
+import pathlib
+import sys
+import unittest
+
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent / "bench"))
+
+from regrade_control_selection import (  # noqa: E402
+    PRESERVE_ON_BLOCKING,
+    UNRESOLVED,
+    rateable_controls,
+    regrade_capability,
+)
+
+CTLQ = {
+    "big": {"grade": "good"},
+    "tiny": {"grade": "good_small_n"},
+    "junk": {"grade": "DISCARDED"},
+}
+BAR = {"recall_retention": 0.5, "off_target_mean": 0.1}
+
+
+def _cap(prior, *, rateable_rate=0.4, with_elided=True):
+    """One capability whose rateable control FAILS and whose 2nd row is elided."""
+    cands = [{
+        "model": "m1", "class": "fire", "quiet_t": 0.25,
+        "off_target_mean": 0.0, "n_valid_negatives": 100,
+        "by_bucket": {}, "best_control": "big", "control_n": 9,
+        "control_rate_025": rateable_rate, "control_rate_at_quiet_t": rateable_rate,
+        "per_control": {
+            "big": {"n": 9, "rate_025": rateable_rate, "rate_at_quiet_t": rateable_rate},
+            "tiny": {"n": 5, "rate_025": 0.9, "rate_at_quiet_t": 0.9},
+        },
+    }]
+    if with_elided:
+        cands.append({
+            "model": "m2", "class": "fire", "quiet_t": 0.25,
+            "off_target_mean": 0.0, "n_valid_negatives": 100,
+            "by_bucket": {"_elided": "summary row"},
+            "best_control": "tiny", "control_n": 5,
+            "control_rate_025": 0.9, "control_rate_at_quiet_t": 0.9,
+            "per_control": {},
+        })
+    return {"capability": "fire",
+            "decision": {"decision": prior, "control": "tiny", "control_n": 5},
+            "candidates": cands}
+
+
+class TestRegradeControlSelection(unittest.TestCase):
+
+    def test_liveness_only_and_unusable_grades_cannot_rate_a_class(self):
+        per = {"big": {"n": 9}, "tiny": {"n": 5}, "junk": {"n": 26}}
+        self.assertEqual(sorted(rateable_controls(per, CTLQ)), ["big"])
+
+    def test_a_publish_on_a_liveness_only_set_is_withdrawn_not_failed(self):
+        out = regrade_capability(_cap("PUBLISH"), CTLQ, BAR)
+        self.assertEqual(out["regraded_decision"], UNRESOLVED)
+        self.assertTrue(out["candidates_unknown"], "the elided row must be named")
+        self.assertTrue(out["changed"])
+
+    def test_rerunning_over_its_own_output_reproduces_unresolved(self):
+        first = regrade_capability(_cap("PUBLISH"), CTLQ, BAR)
+        second = regrade_capability(_cap(first["regraded_decision"]), CTLQ, BAR)
+        self.assertEqual(
+            second["regraded_decision"], UNRESOLVED,
+            "a second --apply hardened an unknown into a definitive verdict")
+        self.assertFalse(second["changed"], "a settled UNRESOLVED must not read as changed")
+
+    def test_a_measured_failure_is_left_alone(self):
+        out = regrade_capability(_cap("NO MODEL CLEARS BAR"), CTLQ, BAR)
+        self.assertEqual(out["regraded_decision"], "NO MODEL CLEARS BAR")
+        self.assertFalse(out["changed"])
+
+    def test_with_no_elided_row_the_verdict_is_definitive(self):
+        out = regrade_capability(_cap("PUBLISH", with_elided=False), CTLQ, BAR)
+        self.assertEqual(out["regraded_decision"], "NO MODEL CLEARS BAR")
+        self.assertEqual(out["status"], "proven")
+
+    def test_a_candidate_that_clears_on_the_rateable_set_still_publishes(self):
+        out = regrade_capability(_cap("PUBLISH", rateable_rate=0.8), CTLQ, BAR)
+        self.assertEqual(out["regraded_decision"], "PUBLISH")
+        self.assertEqual(out["winner"]["control"], "big")
+        self.assertEqual(out["winner"]["control_n"], 9)
+
+    def test_the_preserve_set_names_both_states_and_nothing_else(self):
+        self.assertEqual(sorted(PRESERVE_ON_BLOCKING), sorted(["PUBLISH", UNRESOLVED]))
+
+    def test_branches_resolved_before_a_control_is_read_are_untouched(self):
+        for prior in ("NO CANDIDATE", "NOT SCREENABLE HERE"):
+            out = regrade_capability(
+                {"capability": "x", "decision": {"decision": prior}, "candidates": []},
+                CTLQ, BAR)
+            self.assertEqual(out["regraded_decision"], prior)
+            self.assertEqual(out["status"], "not_affected")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/deploy/detector/tests/test_venue_adjudication_grades.py

@@ -0,0 +1,83 @@
+"""An ungraded control must stop the run, not quietly become eligible to decide.
+
+`liveness_only` and `unusable` are both built by MEMBERSHIP of a grade set, so a
+control with no grade at all falls through both and is treated as able to rate a
+class — the flattering direction. The committed-artifact guard catches it
+downstream, but by then a wrong number exists and may have been quoted.
+
+The same asymmetry is why `--control-quality` defaults to the COMPLETE sorted set
+rather than to one file: the grades live in dated files (the 2026-08-25 record is
+pinned by the score cards that cite it), and a run reading a subset would give the
+sets graded in the omitted file exactly that benefit of the doubt.
+
+STDLIB ONLY — this lane runs `python3 -m unittest discover` with no pip install,
+and `venue_adjudication.py` imports numpy at module scope, so it is loaded here
+with `importlib` under a guard and the whole module is SKIPPED if numpy is absent
+rather than erroring the lane during discovery.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import pathlib
+import unittest
+
+BENCH = pathlib.Path(__file__).resolve().parent.parent / "bench"
+MODULE_PATH = BENCH / "venue_adjudication.py"
+
+
+def _load():
+    spec = importlib.util.spec_from_file_location("venue_adjudication_under_test", MODULE_PATH)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+try:
+    VA = _load()
+except ImportError:  # numpy absent on this runner
+    VA = None
+
+
+@unittest.skipIf(VA is None, "numpy is not installed on this runner")
+class TestControlGradeCompleteness(unittest.TestCase):
+
+    def test_an_ungraded_control_that_is_used_refuses_the_run(self):
+        with self.assertRaises(SystemExit) as caught:
+            VA.assert_every_control_is_graded(
+                ["fire_cctv", "fire_firesense"], {"fire_firesense": {"grade": "good"}})
+        self.assertIn("fire_cctv", str(caught.exception))
+
+    def test_a_fully_graded_set_passes(self):
+        VA.assert_every_control_is_graded(
+            ["fire_cctv", "fire_firesense"],
+            {"fire_cctv": {"grade": "good"}, "fire_firesense": {"grade": "good"}})
+
+    def test_a_set_no_class_references_is_not_required_to_be_graded(self):
+        # `pos_sets` carries every scored set, including off-target ones that no
+        # CLASS_CONTROL entry names. Those cannot become `best_control`, so
+        # demanding a grade for them would refuse runs for no reason.
+        VA.assert_every_control_is_graded(["some_off_target_set"], {})
+
+    def test_discovery_finds_every_dated_grade_file(self):
+        found = [os.path.basename(p) for p in VA.discover_control_quality()]
+        self.assertTrue(found, "no positive-control-quality-*.json discovered")
+        self.assertEqual(found, sorted(found), "discovery must be sorted so later files win")
+        for name in found:
+            self.assertTrue(name.startswith("positive-control-quality-"))
+            self.assertTrue(name.endswith(".json"))
+        # The two the repo carries today. A third is fine; fewer is not.
+        self.assertIn("positive-control-quality-2026-08-25.json", found)
+        self.assertIn("positive-control-quality-2026-08-27.json", found)
+
+    def test_discovery_of_a_missing_directory_is_empty_not_an_exception(self):
+        self.assertEqual(VA.discover_control_quality("/nonexistent/grade/dir"), [])
+
+    def test_the_grade_lists_stay_disjoint(self):
+        # A grade in both lists would make the refusal order-dependent.
+        self.assertFalse(set(VA.LIVENESS_ONLY_GRADES) & set(VA.UNUSABLE_GRADES))
+
+
+if __name__ == "__main__":
+    unittest.main()

package/deploy/detector/trillboards_detector/labels.py

@@ -544,7 +544,37 @@ FALL_1CLS_11X = ModelVocabulary(
     ),
 )
 
-BUILTIN_VOCABULARIES: "tuple[ModelVocabulary, ...]" = (RFDETR_MEDIUM, GH_FORKLIFT_COMBINE, PPE_VYRA_14CLS_V8M, PPE_CONSTRUCTION_17CLS_V8N, PPE_KILLUMINATI_19CLS_V8S, FALL_1CLS_11X,)
+#: Heavy Machinery Detector (venue-adjudicated) — published 2026-08-27 by
+#: scripts/sensing/publish-sensing-model.js. The class list is the artifact's own
+#: (graph metadata key 'names'); the footprint is MEASURED, 593.3125 MiB after a
+#: probe inference via rusage-maxrss, not an estimate from the file size.
+#: Coordinate space MEASURED, not assumed: max|box channel| = 1825.6333 over 120 real frames; / imgsz 640 = 2.8526. pixels at >= 0.2, normalized at <= 0.02, refused in between.
+GH_PPE_VINAYAK_L_CLASS_NAMES: "MappingProxyType[int, str]" = MappingProxyType({
+    0: "hardhat",
+    1: "mask",
+    2: "no hardhat",
+    3: "no mask",
+    4: "no safety vest",
+    5: "person",
+    6: "safety cone",
+    7: "safety vest",
+    8: "machinery",
+    9: "vehicle",
+})
+
+GH_PPE_VINAYAK_L = ModelVocabulary(
+    model_name="gh_ppe_vinayak_l",
+    slot_names=GH_PPE_VINAYAK_L_CLASS_NAMES,
+    logit_slots=10,
+    approx_ram_bytes=622133248,
+    onnx_variant=VariantContract(
+        output_layout="anchor_4_plus_nc",
+        box_units="pixels",
+        box_scale_to_pixels=1.0,
+    ),
+)
+
+BUILTIN_VOCABULARIES: "tuple[ModelVocabulary, ...]" = (RFDETR_MEDIUM, GH_FORKLIFT_COMBINE, PPE_VYRA_14CLS_V8M, PPE_CONSTRUCTION_17CLS_V8N, PPE_KILLUMINATI_19CLS_V8S, FALL_1CLS_11X, GH_PPE_VINAYAK_L,)
 
 
 class ClassIndex:
@@ -638,6 +668,7 @@ class ClassIndex:
 
 
 __all__ = [
+    "GH_PPE_VINAYAK_L",
     "FALL_1CLS_11X",
     "PPE_KILLUMINATI_19CLS_V8S",
     "PPE_CONSTRUCTION_17CLS_V8N",

package/deploy/windows/setup-litertlm.ps1

@@ -211,10 +211,11 @@ function Write-LitertlmConfig {
 # /v1/models answers without ever building an engine, so it cannot tell a working
 # GPU encoder from one that fails on first use.
 function Test-LitertlmVision {
+  param([string]$InferenceModel = "$ModelId,gpu")
   try {
     $dataUri = "data:image/jpeg;base64," + $script:LitertlmProbeJpegB64
     $body = @{
-      model = "$ModelId,gpu"
+      model = $InferenceModel
       messages = @(@{ role = "user"; content = @(
         @{ type = "text"; text = "Reply with the single word: ok" },
         @{ type = "image_url"; image_url = @{ url = $dataUri } }
@@ -227,7 +228,7 @@ function Test-LitertlmVision {
       -TimeoutSec 180 -UseBasicParsing
     return ($resp.StatusCode -eq 200)
   } catch {
-    Log "vision probe did not answer: $_"
+    Log "vision probe for '$InferenceModel' did not answer: $_"
     return $false
   }
 }
@@ -367,23 +368,32 @@ function Get-LitertLmVersion {
   }
 }
 
-# A HEALTHY SERVE IS NOT ENOUGH TO SKIP PROVISIONING.
+# A HEALTHY CONTROL ROUTE IS NOT ENOUGH TO SKIP PROVISIONING.
 #
 # `Test-ServeHealthy` substring-matches the bare model id, and every litert-lm
 # version answers that identically - including the ones that reject the `,gpu`
-# model id the GPU delegate is selected with. So this fast path, which exists to
-# make a repeat run cheap, was also the path that let an already-installed
-# 0.14.0 declare itself ready forever: the hosts that most need the pinned
-# runtime are exactly the ones with a serve already answering. The version is
-# therefore part of the short-circuit condition, not a check further down that a
-# healthy serve never reaches.
+# model id the GPU delegate is selected with, and without building an inference
+# engine. So this fast path may run only after BOTH the pinned version check and
+# a real image inference. Otherwise a failed first install can leave /v1/models
+# answering, and a reinstall falsely declares success without re-testing the
+# operation that just failed.
 $installedLitertLmVersion = Get-LitertLmVersion
-if ((Test-ServeHealthy) -and ($installedLitertLmVersion -eq $LitertLmVersion)) {
-  Complete-Setup
-  Stop-SetupLock
-  exit 0
+$serveHealthy = Test-ServeHealthy
+if ($serveHealthy -and ($installedLitertLmVersion -eq $LitertLmVersion)) {
+  if (Test-LitertlmVision -InferenceModel "$ModelId,gpu") {
+    Complete-Setup
+    Stop-SetupLock
+    exit 0
+  }
+  if (Test-LitertlmVision -InferenceModel $ModelId) {
+    Log "local AI healthy on the previously configured full CPU fallback (slower, but serving)"
+    Complete-Setup
+    Stop-SetupLock
+    exit 0
+  }
+  Log "WARN: the pinned serve answers /v1/models but not a real GPU or CPU image inference; reprovisioning local AI"
 }
-if ((Test-ServeHealthy) -and ($installedLitertLmVersion -ne $LitertLmVersion)) {
+if ($serveHealthy -and ($installedLitertLmVersion -ne $LitertLmVersion)) {
   Log "serve is healthy but litert-lm is $(if ($installedLitertLmVersion) { $installedLitertLmVersion } else { 'unknown' }) not pinned $LitertLmVersion; reinstalling and restarting the serve"
 }
 
@@ -686,7 +696,7 @@ if (-not $healthy) {
 # never builds an engine -- so it cannot see a GPU vision encoder that fails on
 # first USE. If the probe inference does not answer we fall back to the CPU
 # encoder rather than leave this host unable to sense at all.
-if (-not (Test-LitertlmVision)) {
+if (-not (Test-LitertlmVision -InferenceModel "$ModelId,gpu")) {
   Log "WARN: GPU vision encoder did not answer a probe inference; falling back to the CPU encoder"
   Write-LitertlmConfig | Out-Null
   & powershell.exe -NoProfile -ExecutionPolicy Bypass -File $registration -LitertLmPath $litertlmPath -Port $Port *>> $LogPath
@@ -700,7 +710,9 @@ if (-not (Test-LitertlmVision)) {
     Stop-SetupLock
     exit 1
   }
-  # RE-PROBE, with the same probe that sent us here.
+  # RE-PROBE the CPU-vision tier, first keeping GPU inference for hosts where
+  # only the image encoder failed, then using the same bare-model CPU fallback
+  # that LiteRtVlmProvider uses at runtime when the main GPU delegate fails.
   #
   # Test-ServeHealthy above only proves /v1/models answers, and this file's own
   # comment six lines up says that route never builds an engine. So before this
@@ -710,15 +722,18 @@ if (-not (Test-LitertlmVision)) {
   # install: the cascade detected the failure, downgraded a tier, and then
   # verified the downgrade with a check that cannot fail for this reason.
   #
-  # A CPU fallback that cannot infer is not a slower tier. It is a broken
+  # A full CPU fallback that cannot infer is not a slower tier. It is a broken
   # install, and the operator has to hear so at setup time rather than discover
   # it as silence from a camera weeks later.
-  if (-not (Test-LitertlmVision)) {
-    Fail-LocalAi "Gemma is installed and the local AI service is answering, but it could not analyze a test image on either the GPU or the CPU vision encoder. See $LogPath."
+  if (Test-LitertlmVision -InferenceModel "$ModelId,gpu") {
+    Log "local AI healthy on the CPU vision encoder with GPU inference (slower, but serving)"
+  } elseif (Test-LitertlmVision -InferenceModel $ModelId) {
+    Log "local AI healthy on the full CPU fallback (slower, but serving)"
+  } else {
+    Fail-LocalAi "Gemma is installed and the local AI service is answering, but it could not analyze a test image with either GPU inference or the full CPU fallback. See $LogPath."
     Stop-SetupLock
     exit 1
   }
-  Log "local AI healthy on the CPU vision encoder (slower, but serving)"
 } else {
   Log "local AI healthy with the GPU vision encoder"
 }

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.107';
+const SDK_VERSION = '0.2.110';
 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.107";
+declare const SDK_VERSION = "0.2.110";
 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.107';
+const SDK_VERSION = '0.2.110';
 exports._SDK_VERSION = SDK_VERSION;
 // ---------------------------------------------------------------------------
 // ANSI helpers (no external deps)

package/package.json

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