@trillboards/edge-sdk 0.2.106 → 0.2.109

package/deploy/detector/bench/venue_adjudication.py

@@ -0,0 +1,959 @@
+#!/usr/bin/env python3
+"""Re-adjudicate every screened detector against a VENUE-MATCHED negative set.
+
+WHY THIS EXISTS
+---------------
+The 2026-08-25 screen scored 96 artifacts across 35 capabilities against 1,500
+"production" frames. 1,494 of those 1,500 came from one screen type,
+`taxi_rideshare_tv` -- rideshare cabin interiors, 44% of them darker than mean
+pixel 50. Its own report says three times "publishable pending a venue-matched
+negative set". So every "no model clears the bar" verdict and every published
+model's operating threshold describes a car at night, and we sell a CCTV product.
+
+The negative set here is the Phase-3 quiet-hour corpus: real fixed cameras in an
+industrial logistics yard, a hospital hand-wash basin, a big-box retail aisle and
+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 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
+   and a rate on an invalid cell is reported as a FIRING rate, never a false-alarm
+   rate. Where `scripts/sensing/quiet-hour-fleet-plan.json` declares a class, that
+   declaration wins; everything else falls back to the hand grading, and a class
+   with neither is reported `no_absence_declaration`.
+2. Never blended. Every cell carries its own bucket, its own n and its own exact
+   Clopper-Pearson interval. A pooled rate over four scene types describes no
+   promise we sell. Each cell ALSO carries a box-level count, because
+   Clopper-Pearson assumes independent trials and the retail bucket violates that
+   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.
+"""
+from __future__ import annotations
+
+import argparse
+import glob
+import json
+import math
+import os
+from collections import Counter
+
+import numpy as np
+
+# --- sellable capability -> the class names that would carry it ---------------
+# Verbatim from the 2026-08-25 screen so the two adjudications are comparable;
+# changing it would make the before/after a different question.
+CAPS = {
+    "hard hat present": ["helmet", "hardhat", "hard_hat", "hat", "Helmet", "Hardhat", "Hard_hat"],
+    "hard hat ABSENT": ["no-helmet", "no_helmet", "no helmet", "no-hardhat", "nohat", "No-Helmet", "NO-Hardhat", "No_Helmet"],
+    "hi-vis vest present": ["vest", "safety vest", "safety_vest", "safety-vest", "Vest", "Safety Vest"],
+    "hi-vis vest ABSENT": ["no-vest", "no vest", "no_vest", "novest", "no-safety vest", "no_safety_vest", "No-Vest", "NO-Safety Vest"],
+    "face mask present": ["mask", "Mask", "with_mask", "face-mask-medical"],
+    "face mask ABSENT": ["no-mask", "no_mask", "without_mask", "NO-Mask", "No-Mask"],
+    "gloves present": ["gloves", "glove", "Glove", "Gloves", "glove_hand", "gloved_hand"],
+    "gloves ABSENT": ["no-gloves", "no-glove", "no_glove", "No-Glove", "bare_hand"],
+    "goggles / eye pro": ["goggles", "glass", "glasses", "Glass", "Goggles"],
+    "safety boots": ["boots", "Boots", "safety shoes", "safety-boot", "shoes"],
+    "apron": ["Apron", "apron"],
+    "hairnet": ["Hairnet", "hairnet"],
+    "fire": ["fire", "Fire"],
+    "smoke": ["smoke", "Smoke"],
+    "smoking (cigarette)": ["Cigarette", "cigarette", "smoking"],
+    "gun": ["gun", "Gun", "pistol", "handgun", "rifle", "shotgun", "Pistol", "Handgun", "Shotgun", "firearm"],
+    "knife": ["knife", "Knife"],
+    "weapon (generic)": ["weapon", "Weapon"],
+    "person down / fall": ["fall", "Fall", "fallen", "Fallen", "fall-detected", "Fall-Detected", "down"],
+    "forklift": ["forklift", "Forklift", "forklift-partial", "Forklift-Partial", "Yoto", "yoto"],
+    "heavy machinery": ["machinery", "machine", "excavator", "excavators", "wheel loader", "wheel_loader",
+                        "dozer", "backhoe_loader", "mobile_crane", "tower_crane", "compactor",
+                        "concrete_mixer_truck", "grader", "dump truck", "dump_truck"],
+    "pallet": ["pallet", "Pallet"],
+    "person / head count": ["person", "Person", "human", "Human", "head", "Head", "worker", "Worker"],
+    "vehicle / queue": ["vehicle", "vehicle queue", "Vehicle"],
+    "shopping cart": ["cart", "Cart", "trolley", "shopping_cart"],
+    "spill": ["Spill", "spill"],
+    "shoplifting / theft": ["shoplifting", "theft", "Shoplifting", "Theft"],
+    "door": ["door", "Door"],
+    "window": ["window", "Window"],
+    "phone use": ["phone", "phone_call", "Phone", "cell phone"],
+    # `mouse` is carried from the 2026-08-25 table so the two adjudications stay
+    # comparable, and it is SEMANTICALLY WRONG for COCO: category 74 is a COMPUTER
+    # mouse. It cannot win here -- it would have to clear >=50% recall on n_rodent,
+    # a set of rodent photographs -- but if a COCO-vocabulary model ever takes the
+    # `rodent` row, that is the reason and the row is void.
+    "rodent": ["mouse", "Mouse", "rat", "rodent"],
+    "shelf gap / OOS": ["void", "Void", "gap", "empty"],
+    "traffic cone": ["safety cone", "Safety Cone", "safety_cone"],
+    "fire extinguisher": ["fire_extinguisher", "Fire_Extinguisher"],
+    "ladder": ["ladder", "Ladder"],
+}
+
+# --- class name -> positive-control set(s) that should make that class fire ----
+# '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_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"],
+    "safety_vest": ["helmet", "n_heavy", "n_cone", "ppe_full"], "safety-vest": ["helmet", "n_heavy", "n_cone", "ppe_full"],
+    "mask": ["ppe_full"], "with_mask": ["ppe_full"], "face-mask-medical": ["ppe_full"],
+    "goggles": ["ppe_full"], "glass": ["ppe_full"], "glasses": ["ppe_full"],
+    "boots": ["ppe_full"], "safety shoes": ["ppe_full"], "safety-boot": ["ppe_full"], "shoes": ["ppe_full"],
+    "gloves": ["ppe_full", "wc_glove"], "glove": ["ppe_full", "wc_glove"], "glove_hand": ["wc_glove", "ppe_full"],
+    "apron": ["wc_apron"], "Apron": ["wc_apron"], "hairnet": ["n_hairnet"], "Hairnet": ["n_hairnet"],
+    "safety cone": ["n_cone"], "safety_cone": ["n_cone"],
+    "fire_extinguisher": ["n_extinguisher"], "ladder": ["n_ladder"],
+    "person": ["helmet", "ppe_full", "n_crowd"], "worker": ["ppe_full", "helmet", "n_crowd"],
+    "human": ["helmet", "ppe_full", "n_crowd"], "head": ["helmet", "n_crowd"],
+    "forklift": ["forklift"], "forklift-partial": ["forklift"], "Forklift-Partial": ["forklift"], "yoto": ["forklift"],
+    "pallet": ["n_pallet"], "machinery": ["n_heavy"], "machine": ["n_heavy"],
+    "excavator": ["n_heavy"], "excavators": ["n_heavy"], "dozer": ["n_heavy"],
+    "wheel loader": ["n_heavy"], "wheel_loader": ["n_heavy"], "backhoe_loader": ["n_heavy"],
+    "mobile_crane": ["n_heavy"], "tower_crane": ["n_heavy"], "compactor": ["n_heavy"],
+    "concrete_mixer_truck": ["n_heavy"], "grader": ["n_heavy"], "dump truck": ["n_heavy"], "dump_truck": ["n_heavy"],
+    "vehicle": ["n_traffic"], "vehicle queue": ["n_traffic"],
+    "gun": ["gun_clean", "weapon_cctv"], "pistol": ["gun_clean", "weapon_cctv"], "handgun": ["gun_clean", "weapon_cctv"],
+    "rifle": ["gun_clean"], "shotgun": ["gun_clean"], "weapon": ["weapon_cctv", "gun_clean"],
+    "firearm": ["gun_clean", "weapon_cctv"], "knife": ["knife_cctv", "weapon_cctv", "n_knife"],
+    "fall": ["fall_cctv"], "fallen": ["fall_cctv"], "fall-detected": ["fall_cctv"],
+    "Fall-Detected": ["fall_cctv"], "down": ["fall_cctv"],
+    "door": ["n_door"], "window": ["n_window"], "phone": ["n_phone"], "cell phone": ["n_phone"],
+    "phone_call": ["n_phone"], "mouse": ["n_rodent"], "void": ["n_shelfgap"],
+    "cart": ["wc_cart", "n_trolley"], "trolley": ["wc_cart", "n_trolley"], "shopping_cart": ["wc_cart", "n_trolley"],
+    "spill": ["wc_spill", "n_spill"], "Spill": ["wc_spill", "n_spill"],
+    "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.
+
+    The control lookup MUST go through this. A case-sensitive lookup misses
+    `Fire_Extinguisher` against a table keyed `fire_extinguisher` and the
+    capability then reports UNINFORMATIVE -- "no usable positive control exists"
+    -- when the control is sitting right there. That reads as a finding about the
+    world and is a finding about a dict.
+    """
+    return name.strip().lower().replace("_", " ").replace("-", " ")
+
+
+#: CLASS_CONTROL re-keyed by normalised name, built once.
+CLASS_CONTROL_N = {}
+for _k, _v in CLASS_CONTROL.items():
+    CLASS_CONTROL_N.setdefault(normalise_class(_k), []).extend(_v)
+CLASS_CONTROL_N = {k: sorted(set(v), key=v.index) for k, v in CLASS_CONTROL_N.items()}
+
+
+# --- capability -> the plan file's own class, where one covers it -------------
+# The plan declares `expectedOnQuiet` for nine classes. Where it speaks, it wins.
+CAP_TO_PLAN_CLASS = {
+    "person / head count": "person_count",
+    "person down / fall": "person_on_the_ground",
+    "spill": "spill_on_floor",
+    "fire": "fire_or_smoke_visible",
+    "smoke": "fire_or_smoke_visible",
+    "forklift": "forklift_present",
+    "hard hat ABSENT": "person_missing_required_ppe",
+    "hi-vis vest ABSENT": "person_missing_required_ppe",
+    "face mask ABSENT": "person_missing_required_ppe",
+    "gloves ABSENT": "person_missing_required_ppe",
+    "phone use": "person_using_phone",
+}
+
+# --- capability -> the hand-grading key, for classes the plan does not cover ---
+CAP_TO_GRADE_CLASS = {
+    "hard hat present": "hard_hat", "hi-vis vest present": "hi_vis_vest",
+    "face mask present": "face_mask", "gloves present": "gloves",
+    "goggles / eye pro": "goggles", "safety boots": "safety_boots",
+    "apron": "apron", "hairnet": "hairnet", "smoking (cigarette)": "cigarette",
+    "gun": "gun", "knife": "knife", "weapon (generic)": "weapon_generic",
+    "heavy machinery": "heavy_machinery", "pallet": "pallet",
+    "vehicle / queue": "vehicle", "shopping cart": "shopping_cart",
+    "shoplifting / theft": "shoplifting", "door": "door", "window": "window",
+    "rodent": "rodent", "shelf gap / OOS": "shelf_gap",
+    "traffic cone": "traffic_cone", "fire extinguisher": "fire_extinguisher",
+    "ladder": "ladder",
+}
+
+
+# --- what the 2026-08-25 taxi-negative screen decided, for the before/after ----
+# Historical fact, embedded so the comparison is reproducible from this file
+# alone; the source `ranking.json` was a scratch artifact and is not committed.
+PRIOR_VERDICT = {
+    'hard hat present': ('PUBLISH', 'ppe_vyra_14cls_v8m'),
+    'hard hat ABSENT': ('NOT SCREENABLE HERE', None),
+    'hi-vis vest present': ('NO MODEL CLEARS BAR', 'ppe_boots_goggles_v8s'),
+    'hi-vis vest ABSENT': ('NOT SCREENABLE HERE', None),
+    'face mask present': ('NO MODEL CLEARS BAR', 'ppe_mask_3cls_v8n'),
+    'face mask ABSENT': ('NOT SCREENABLE HERE', None),
+    'gloves present': ('NO MODEL CLEARS BAR', 'ppe_sh17_17cls_11x'),
+    'gloves ABSENT': ('NOT SCREENABLE HERE', None),
+    'goggles / eye pro': ('NO MODEL CLEARS BAR', 'ppe_vyra_14cls_v8m'),
+    'safety boots': ('NO MODEL CLEARS BAR', 'ppe_sh17_17cls_11x'),
+    'apron': ('UNINFORMATIVE', None),
+    'hairnet': ('UNINFORMATIVE', None),
+    'fire': ('NO MODEL CLEARS BAR', 'fire_smoke_weslleyskah_11n'),
+    'smoke': ('AMBIGUOUS NEGATIVE SET', 'fire_smoke_weslleyskah_11n'),
+    'smoking (cigarette)': ('UNINFORMATIVE', None),
+    'gun': ('NO MODEL CLEARS BAR', 'gh_weapon_activeshooter_11'),
+    'knife': ('NO MODEL CLEARS BAR', 'gh_weapon_nihal_11s'),
+    'weapon (generic)': ('NO MODEL CLEARS BAR', 'weapon_generic_v8m'),
+    'person down / fall': ('PUBLISH', 'gh_fall_tonlong'),
+    'forklift': ('PUBLISH', 'gh_forklift_combine'),
+    'heavy machinery': ('PUBLISH', 'ppe_construction_17cls_v8n'),
+    'pallet': ('NO MODEL CLEARS BAR', 'gh_forklift_pallet_11s'),
+    'person / head count': ('NOT SCREENABLE HERE', None),
+    'vehicle / queue': ('AMBIGUOUS NEGATIVE SET', 'gh_ppe_vinayak_l'),
+    'shopping cart': ('NO CANDIDATE', None),
+    'spill': ('UNINFORMATIVE', None),
+    'shoplifting / theft': ('UNINFORMATIVE', None),
+    'door': ('NOT SCREENABLE HERE', None),
+    'window': ('NOT SCREENABLE HERE', None),
+    'phone use': ('NOT SCREENABLE HERE', None),
+    'rodent': ('NO MODEL CLEARS BAR', 'rodent_pulkit'),
+    'shelf gap / OOS': ('NO MODEL CLEARS BAR', 'hf_shelfgap'),
+    'traffic cone': ('AMBIGUOUS NEGATIVE SET', 'gh_ppe_vinayak_l'),
+    'fire extinguisher': ('PUBLISH', 'ppe_killuminati_19cls_v8s'),
+    'ladder': ('UNINFORMATIVE', None),
+}
+
+#: Artifacts the shipped service REFUSES to load, and what replaces them. An
+#: adjudication that names an unloadable artifact is worse than one that omits
+#: it: the row looks shippable and the model cannot be published.
+#: `gh_fall_tonlong` declares `Violence` at slot 0 and `violence` at slot 6;
+#: `labels.py::normalize_class_name` folds them to one name and ModelVocabulary
+#: raises at construction. `gh_fall_tonlong_v2` is the same weights re-exported
+#: with the slots disambiguated by index, so the numbers are unchanged and only
+#: the name the table prints moves.
+SUPERSEDED = {"gh_fall_tonlong": "gh_fall_tonlong_v2"}
+
+
+GRID = np.round(np.arange(0.05, 0.9751, 0.0125), 4)
+QUIET_MAX_FIRE = 0.01           # the 2026-08-25 bar: <1% firing on valid negatives
+RECALL_RETENTION_BAR = 0.50     # "keeps >=50% of positive-control detections"
+OFF_TARGET_BAR = 0.10           # "<=10% mean firing on control sets built for other things"
+PRODUCTION_EMPTY_PRIOR = 0.847  # cctv-detector-tier.md's production frame prior
+
+
+def clopper_pearson(k: int, n: int, alpha: float = 0.05):
+    """Exact binomial interval. A rate on 14 frames and a rate on 480 are not the
+    same claim, and only the interval says so."""
+    if n == 0:
+        return [None, None]
+    from math import inf
+    def beta_ppf(p, a, b):
+        # bisection on the regularised incomplete beta; no scipy on the box
+        if a <= 0:
+            return 0.0
+        if b <= 0:
+            return 1.0
+        lo, hi = 0.0, 1.0
+        for _ in range(200):
+            mid = (lo + hi) / 2
+            if _betainc(a, b, mid) < p:
+                lo = mid
+            else:
+                hi = mid
+        return (lo + hi) / 2
+    lo = 0.0 if k == 0 else beta_ppf(alpha / 2, k, n - k + 1)
+    hi = 1.0 if k == n else beta_ppf(1 - alpha / 2, k + 1, n - k)
+    return [round(lo, 6), round(hi, 6)]
+
+
+def _betainc(a: float, b: float, x: float) -> float:
+    """Regularised incomplete beta via the continued fraction (Lentz)."""
+    if x <= 0:
+        return 0.0
+    if x >= 1:
+        return 1.0
+    lbeta = math.lgamma(a) + math.lgamma(b) - math.lgamma(a + b)
+    front = math.exp(math.log(x) * a + math.log(1 - x) * b - lbeta) / a
+    f, c, d = 1.0, 1.0, 0.0
+    for i in range(0, 300):
+        m = i // 2
+        if i == 0:
+            num = 1.0
+        elif i % 2 == 0:
+            num = (m * (b - m) * x) / ((a + 2 * m - 1) * (a + 2 * m))
+        else:
+            num = -((a + m) * (a + b + m) * x) / ((a + 2 * m) * (a + 2 * m + 1))
+        d = 1.0 + num * d
+        d = 1e-30 if abs(d) < 1e-30 else d
+        d = 1.0 / d
+        c = 1.0 + num / c
+        c = 1e-30 if abs(c) < 1e-30 else c
+        f *= c * d
+        if abs(1.0 - c * d) < 1e-12:
+            break
+    r = front * (f - 1.0)
+    if x < (a + 1) / (a + b + 2):
+        return r
+    # `_betainc(b, a, 1 - x)` is the SAME CALL when a == b and x == 0.5, so the
+    # reflection recursed forever -- and `beta_ppf` starts its bisection at exactly
+    # 0.5, so any Clopper-Pearson interval with symmetric beta parameters (midpoint
+    # successes in an odd-sized sample) raised RecursionError instead of returning.
+    # I(0.5; a, a) = 0.5 by symmetry; take it directly.
+    if a == b and abs(x - 0.5) < 1e-15:
+        return 0.5
+    return 1.0 - _betainc(b, a, 1 - x)
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--out-dir", required=True, help="directory of <alias>.npz + _index.json")
+    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", 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()
+
+    combo = json.load(open(args.combo))
+    grading = json.load(open(args.grading))
+    plan = json.load(open(args.plan))
+    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"]
+    buckets = np.array([m.get("bucket") or "" for m in meta])
+    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
+    # 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 a spill. Read the grades, do not enumerate the bad ones
+    # from memory.
+    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
+    # drawn from 72 SECONDS are ~5 frames per second of one aisle. Same n, very
+    # different evidence, and only the span says which you are holding.
+    src_index = {}
+    src_path = os.path.join(os.path.dirname(args.combo), "srcframes_index.json")
+    if os.path.exists(src_path):
+        for r in json.load(open(src_path)):
+            src_index.setdefault(r["bucket"], {})[r["box"]] = r.get("src_duration_sec") or 0
+
+    comp = {"negative_set": {}, "positive_controls": {}}
+    for b in sorted(set(buckets[is_neg].tolist())):
+        m = is_neg & (buckets == b)
+        boxes = sorted({meta[i]["box"] for i in np.where(m)[0]})
+        span = sum(src_index.get(b, {}).values()) / 3600.0
+        comp["negative_set"][b] = {
+            "frames": int(m.sum()), "boxes": len(boxes),
+            "source_span_hours": round(span, 4),
+            "seconds_between_frames": (round(span * 3600 / int(m.sum()), 2)
+                                       if m.sum() and span else None),
+            "corpora": sorted({meta[i]["corpus"] for i in np.where(m)[0]}),
+            "box_ids": boxes,
+        }
+    for s in pos_sets:
+        m = sets == ("pos:" + s)
+        g = (ctlq.get(s) or {})
+        comp["positive_controls"][s] = {
+            "frames": int(m.sum()), "grade": g.get("grade"),
+            "domain": g.get("domain"), "citable": s not in unusable,
+        }
+
+    def validity(cap: str, bucket: str):
+        """Is this bucket a valid NEGATIVE for this capability?
+
+        Returns (verdict, source). `valid` and `weak` may carry a false-alarm
+        rate; `invalid` and `none` may carry only a firing rate.
+        """
+        pc = CAP_TO_PLAN_CLASS.get(cap)
+        if pc:
+            # the plan declares three buckets; retail and office are the two
+            # halves of its `indoor_retail_and_office`, so its declaration
+            # covers both. Splitting them is a refinement, not a contradiction.
+            pb = {"indoor_retail": "indoor_retail_and_office",
+                  "indoor_office_lab": "indoor_retail_and_office"}.get(bucket, bucket)
+            d = ((plan["classes"].get(pc) or {}).get("expectedOnQuiet") or {}).get(pb)
+            if d == "never":
+                return "valid", f"plan:{pc}=never"
+            if d == "possible":
+                return "invalid", f"plan:{pc}=possible"
+        gk = CAP_TO_GRADE_CLASS.get(cap)
+        if gk:
+            d = ((grading.get("per_class") or {}).get(gk) or {}).get(bucket)
+            if d == "absent":
+                return "valid", f"graded:{gk}=absent"
+            if d == "not_observed":
+                return "weak", f"graded:{gk}=not_observed"
+            if d in ("PRESENT", "AMBIGUOUS"):
+                return "invalid", f"graded:{gk}={d}"
+        return "none", "no_absence_declaration"
+
+    models = {}
+    for alias, info in index.items():
+        if not info.get("ok"):
+            continue
+        p = os.path.join(args.out_dir, alias + ".npz")
+        if not os.path.exists(p):
+            continue
+        d = np.load(p)
+        ms = d["max_scores"]
+        names = info.get("names")
+        if names:
+            names = {int(k): v for k, v in names.items()}
+        else:                                   # RF-DETR: COCO category ids
+            coco = json.load(open(os.path.join(os.path.dirname(args.combo), "coco91.json")))
+            names = {int(k): v for k, v in coco.items()}
+        models[alias] = {"info": info, "ms": ms, "names": names,
+                         "lat_p50_ms": float(np.percentile(d["lat"], 50))}
+
+    # ---- the empty-frame prior, MEASURED on venue footage -------------------
+    # Every `vlm_calls_saved` in this file is reweighted to 0.847 empty frames,
+    # which came off the RIDESHARE fleet. A parked cab with nobody in it is empty
+    # most of the time; a shop is not. The gate's own person detector says so:
+    # `rfdetr_medium` (100% rollout, the artifact actually deciding this today)
+    # sees a person in half to nearly all venue frames depending on the bucket.
+    #
+    # Reported, never substituted into the gate arithmetic above, because
+    # "detector sees no person" is a proxy for "empty" and not a label -- these
+    # frames carry no person ground truth (`person_count` is `possible` in all
+    # three plan buckets, so there is no valid negative for it here either).
+    # It is a MEASURED CEILING on what a person-gated cascade could save in a
+    # venue, and it is far below what the taxi prior implies.
+    venue_prior = {"_what": "share of venue frames with NO person detected by "
+                            "rfdetr_medium, per bucket, at three confidences",
+                   "_caveat": "a detector verdict, not a label. Reported beside the "
+                              "carried 0.847 taxi prior, never substituted for it.",
+                   "_source": None, "by_bucket": {}}
+    rf = models.get("PUB__rfdetr_medium") or models.get("rfdetr_medium")
+    if rf is not None:
+        venue_prior["_source"] = ("PUB__rfdetr_medium" if "PUB__rfdetr_medium" in models
+                                  else "rfdetr_medium")
+        person_idx = next((i for i, n in rf["names"].items() if n == "person"), None)
+        if person_idx is not None:
+            col = rf["ms"][:, person_idx]
+            for b in sorted(set(buckets[is_neg].tolist())):
+                m = is_neg & (buckets == b)
+                venue_prior["by_bucket"][b] = {
+                    "n": int(m.sum()),
+                    "empty_at_0.25": float((col[m] < 0.25).mean()),
+                    "empty_at_0.50": float((col[m] < 0.50).mean()),
+                    "empty_at_0.70": float((col[m] < 0.70).mean()),
+                }
+            allm = is_neg
+            venue_prior["all_venue"] = {
+                "n": int(allm.sum()),
+                "empty_at_0.50": float((col[allm] < 0.50).mean()),
+                "taxi_prior_carried_in_gate_arithmetic": PRODUCTION_EMPTY_PRIOR,
+            }
+
+    # ---- control: do the VM re-exports describe the SHIPPED artifacts? -----
+    # Four specialists and rfdetr are run twice, once from a re-export of the
+    # upstream weights and once from `pubonnx/` -- the exact bytes in
+    # sensing_model_registry. A re-export of the same .pt is NOT guaranteed to be
+    # the same artifact (fp32 export moved YOLOE's recall 28 points, §3), so the
+    # pair decides whether this whole adjudication may be read as describing what
+    # is deployed. Compared on the SAME frames through the SAME decode: only the
+    # artifact differs.
+    repro = {}
+    for alias, M in models.items():
+        if not alias.startswith("PUB__"):
+            continue
+        base = alias[len("PUB__"):]
+        other = models.get(base)
+        if other is None:
+            repro[base] = {"paired": False,
+                           "why": "no re-export of this artifact on the box"}
+            continue
+        a, b = M["ms"], other["ms"]
+        if a.shape != b.shape:
+            repro[base] = {"paired": False, "why": f"shape {a.shape} vs {b.shape}"}
+            continue
+        d = np.abs(a - b)
+        # a firing decision is what we actually consume, so disagreement is
+        # counted at the threshold, not only as a residual
+        dis = {}
+        for t in (0.25, 0.50, 0.70):
+            dis[f"decision_disagreement_{t:.2f}"] = float(((a >= t) != (b >= t)).mean())
+        repro[base] = {"paired": True, "n_frames": int(a.shape[0]),
+                       "n_classes": int(a.shape[1]),
+                       "max_abs_score_delta": float(d.max()),
+                       "mean_abs_score_delta": float(d.mean()), **dis}
+
+    rows = []
+    for cap, wanted in CAPS.items():
+        cands = []
+        for alias, M in models.items():
+            if alias in SUPERSEDED and SUPERSEDED[alias] in models:
+                continue
+            hit = [(ci, cn) for ci, cn in M["names"].items() if cn in wanted]
+            if not hit:
+                continue
+            ci, cn = hit[0]
+            col = M["ms"][:, ci]
+
+            # -------- negative side, per bucket, never blended ---------------
+            by_bucket, valid_mask = {}, np.zeros(len(col), dtype=bool)
+            for b in sorted(set(buckets[is_neg].tolist())):
+                m = is_neg & (buckets == b)
+                v, src = validity(cap, b)
+                sc = col[m]
+                k50 = int((sc >= 0.50).sum())
+                # A BOX-LEVEL view beside the frame-level one. Clopper-Pearson
+                # assumes independent trials and the retail bucket flatly violates
+                # that -- 400 frames drawn 0.22 s apart from one aisle. Reporting
+                # how many distinct SOURCE BOXES fire, out of how many exist, gives
+                # the reader the conservative unit without pretending there is one
+                # correct n. Neither number is "the" rate; the pair is.
+                fb = [meta[i]["box"] for i in np.where(m)[0]]
+                fired_boxes = {fb[t] for t in range(len(fb)) if sc[t] >= 0.50}
+                by_bucket[b] = {
+                    "n": int(m.sum()), "validity": v, "validity_source": src,
+                    "fire_050": float((sc >= 0.50).mean()),
+                    "fire_050_ci95": clopper_pearson(k50, int(m.sum())),
+                    "ci95_assumes_independent_frames": True,
+                    "boxes_firing_050": len(fired_boxes),
+                    "boxes": len(set(fb)),
+                    "max_score": float(sc.max()) if sc.size else 0.0,
+                    "metric": ("false_alarm_rate" if v in ("valid", "weak")
+                               else "firing_rate_only"),
+                }
+                if v in ("valid", "weak"):
+                    valid_mask |= m
+
+            n_valid = int(valid_mask.sum())
+            # THE THRESHOLD MUST HOLD IN EVERY VALID BUCKET, NOT IN THEIR UNION.
+            # Choosing it from the pooled mask is the "never blended" rule broken by
+            # the tool that states it: the hospital sink is 320 frames and the
+            # industrial yard 480, so a class firing 3% on the sink and 0% elsewhere
+            # pools to 0.8% and passes, having failed the advertised bar for that
+            # scene type. `quiet_fire_rate` is correspondingly the WORST bucket's
+            # rate at that threshold, never the average.
+            quiet_t, quiet_fire, quiet_by_bucket = None, None, None
+            valid_names = [b for b, v in by_bucket.items()
+                           if v["validity"] in ("valid", "weak")]
+            if n_valid and valid_names:
+                cols = {b: col[is_neg & (buckets == b)] for b in valid_names}
+                for t in GRID:
+                    rates = {b: float((sc >= t).mean()) for b, sc in cols.items()}
+                    if max(rates.values()) < QUIET_MAX_FIRE:
+                        quiet_t = float(t)
+                        quiet_fire = max(rates.values())
+                        quiet_by_bucket = {b: r for b, r in sorted(rates.items())}
+                        break
+
+            # -------- positive side: same artifact, same preprocessing -------
+            ctl_names = CLASS_CONTROL_N.get(normalise_class(cn), [])
+            best_ctl, best_rate, best_at_qt = None, None, None
+            per_ctl = {}
+            for s in ctl_names:
+                if s in unusable or ("pos:" + s) not in combo["ranges"]:
+                    continue
+                m = sets == ("pos:" + s)
+                if not m.sum():
+                    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,
+                              "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
+
+            # -------- off-target: control sets built for OTHER things --------
+            off = {}
+            for s in pos_sets:
+                if s in ctl_names or s in unusable:
+                    continue
+                m = sets == ("pos:" + s)
+                if not m.sum() or quiet_t is None:
+                    continue
+                off[s] = float((col[m] >= quiet_t).mean())
+            off_mean = (sum(off.values()) / len(off)) if off else None
+            off_worst = max(off.items(), key=lambda kv: kv[1]) if off else None
+            # Keep the mean, the worst and anything materially firing; drop the
+            # long tail of zeros. 24 control sets x 290 candidate rows of "0.0" is
+            # ~7,000 lines of committed noise, and the diagnostic question --
+            # WHICH other thing does this model confuse for its own class -- is
+            # answered by the non-zero entries alone.
+            off_notable = {k: v for k, v in off.items() if v >= 0.05}
+
+            # -------- cascade gate, at the production empty-frame prior ------
+            gate = None
+            if quiet_t is not None and best_rate is not None:
+                recall = best_at_qt or 0.0
+                gate = {
+                    "empty_prior": PRODUCTION_EMPTY_PRIOR,
+                    "empty_prior_provenance": (
+                        "cctv-detector-tier.md's production frame prior, measured on the "
+                        "rideshare fleet. NOT measured for a venue; it is carried here only "
+                        "so the two adjudications are comparable."),
+                    "operating_conf": quiet_t,
+                    "vlm_calls_saved": PRODUCTION_EMPTY_PRIOR * (1.0 - quiet_fire),
+                    "events_lost": 1.0 - recall,
+                    "total_calls_removed": (PRODUCTION_EMPTY_PRIOR * (1.0 - quiet_fire)
+                                            + (1.0 - PRODUCTION_EMPTY_PRIOR) * (1.0 - recall)),
+                }
+
+            cands.append({
+                "model": alias, "class": cn, "class_index": int(ci),
+                # `M["info"]`, NOT the bare `info` -- that name leaks out of the
+                # loop that BUILT `models` and still points at whichever index
+                # entry it saw last, so every candidate read as shipped_bytes
+                # True. Python's loop-variable scope, caught by an elision that
+                # elided nothing.
+                "shipped_bytes": bool(M["info"].get("shipped_bytes")),
+                "by_bucket": by_bucket,
+                "n_valid_negatives": n_valid,
+                "quiet_t": quiet_t,
+                "quiet_fire_rate": quiet_fire,
+                "quiet_fire_rate_is": "the WORST valid bucket at quiet_t, not a pooled rate",
+                "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),
+                "off_target_notable": off_notable,
+                "gate": gate,
+                "lat_p50_ms": M["lat_p50_ms"],
+            })
+
+        # Tie-break TOWARD the shipped bytes. A specialist appears twice -- once
+        # as `PUB__<id>` (the artifact in sensing_model_registry) and once as a
+        # re-export -- and they agree to ~1e-06, so an arbitrary tie-break would
+        # name whichever the dict happened to yield. Naming the deployed artifact
+        # is the useful half of the pair.
+        cands.sort(key=lambda c: (-(c["control_rate_at_quiet_t"] or 0), c["quiet_t"] or 1,
+                                  not c["shipped_bytes"], c["model"]))
+        # Per-bucket detail for the candidates the decision could turn on -- the
+        # top five and every shipped artifact -- and summary rows for the rest.
+        # All 290 candidate rows at full detail are 795 KB of committed JSON, 45%
+        # of it per-bucket cells for models that lost by 60 points. The verdict
+        # stays auditable: every candidate keeps its quiet threshold, its control
+        # recall and its valid-negative count, which is everything `decide` reads.
+        for rank, c in enumerate(cands):
+            if rank >= 5 and not c["shipped_bytes"]:
+                c["by_bucket"] = {"_elided": "summary row; rerun the tool for "
+                                            "per-bucket cells on every candidate"}
+                c["per_control"] = {}
+                c["gate"] = None
+
+        now = decide(cap, cands)
+        was, was_model = PRIOR_VERDICT.get(cap, (None, None))
+        rows.append({"capability": cap, "n_candidates": len(cands),
+                     "prior_decision_taxi_negatives": was,
+                     "prior_model": was_model,
+                     "changed": bool(was is not None and was != now["decision"]),
+                     "decision": now, "candidates": cands})
+
+    json.dump({
+        "schema": "trillboards.venue-adjudication/1",
+        "negative_set": "venue-phase3-source-2026-08-26",
+        "supersedes": "the 1,500-frame `production` negative set of 2026-08-25, "
+                      "1,494 of which were taxi_rideshare_tv cabin interiors",
+        "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,
+        "capabilities": rows,
+    }, open(args.out, "w"), indent=1)
+
+    if args.markdown:
+        with open(args.markdown, "w") as fh:
+            fh.write(render_markdown(rows, comp))
+
+    print(json.dumps({"capabilities": len(rows),
+                      "models_adjudicated": len(models),
+                      "negative_frames": int(is_neg.sum()),
+                      "buckets": dict(Counter(buckets[is_neg].tolist()))}, indent=1))
+
+
+def render_markdown(rows: list, comp: dict) -> str:
+    """The runbook table, emitted rather than hand-typed.
+
+    Hand-copying a 35-row table into prose is how a runbook starts disagreeing
+    with its own artifact -- this file already carries a twin count that was
+    wrong in nine places for a day.
+    """
+    out = []
+    out.append("    capability            was (taxi negatives)   now (venue negatives)  model / why")
+    out.append("    " + "-" * 108)
+    for r in rows:
+        d = r["decision"]
+        was = r["prior_decision_taxi_negatives"] or "-"
+        now = d["decision"]
+        mark = "*" if r["changed"] else " "
+        who = d.get("model") or d.get("best_effort") or ""
+        extra = ""
+        if now == "PUBLISH":
+            c = next((c for c in r["candidates"] if c["model"] == who), None)
+            if c:
+                extra = (" conf %.3f, keeps %.0f%% of %s (n=%s), <1%% on %d venue negs"
+                         % (c["quiet_t"] or 0, 100 * (c["control_rate_at_quiet_t"] or 0),
+                            c["best_control"], c["control_n"], c["n_valid_negatives"]))
+        out.append("    %s%-21s %-22s %-22s %s%s"
+                   % (mark, r["capability"], _short(was), _short(now), who, extra))
+    out.append("")
+    out.append("    * = the verdict moved when the negative set changed.")
+    out.append("")
+    out.append("    negative set composition (span is the source video the frames came from --")
+    out.append("    a frame count is not an independence claim):")
+    for b, v in sorted(comp["negative_set"].items(),
+                       key=lambda kv: -kv[1]["source_span_hours"]):
+        out.append("      %-26s %4d frames  %2d boxes  %6.2f h span  1 per %7s s  %s"
+                   % (b, v["frames"], v["boxes"], v["source_span_hours"],
+                      v["seconds_between_frames"], ",".join(v["corpora"])))
+    return "\n".join(out) + "\n"
+
+
+def _short(v: str) -> str:
+    return {"NOT SCREENABLE HERE": "NOT SCREENABLE",
+            "AMBIGUOUS NEGATIVE SET": "AMBIGUOUS NEGSET",
+            "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.
+
+    Same ladder as the 2026-08-25 screen. Only the negative set differs.
+    """
+    if not cands:
+        return {"decision": "NO CANDIDATE",
+                "why": "no sourced artifact declares a class for this capability"}
+    if all(c["n_valid_negatives"] == 0 for c in cands):
+        return {"decision": "NOT SCREENABLE HERE",
+                "why": "no bucket of the venue corpus is a valid negative for this class -- "
+                       "either the plan file declares it `possible` everywhere, or the corpus "
+                       "was hand-graded as containing it. Firing here can be correct, so no "
+                       "false-alarm rate exists to compute."}
+    live = [c for c in cands if (c["control_rate_025"] or 0) > 0]
+    if not live:
+        if all(c["best_control"] is None for c in cands):
+            return {"decision": "UNINFORMATIVE",
+                    "why": "no usable positive control exists for this class, so no firing "
+                           "rate here is a finding"}
+        return {"decision": "NO MODEL CLEARS BAR",
+                "why": "no candidate fires on its positive control"}
+    retained = [c for c in live if (c["control_rate_at_quiet_t"] or 0) >= RECALL_RETENTION_BAR]
+    if not retained:
+        best = max(live, key=lambda c: (c["control_rate_at_quiet_t"] or 0))
+        r = best["control_rate_at_quiet_t"]
+        return {"decision": "NO MODEL CLEARS BAR", "best_effort": best["model"],
+                "why": "candidates are alive but collapse when forced quiet: the best (%s, "
+                       "class '%s') keeps only %s of its positive-control detections at the "
+                       "confidence needed for <1%% firing on the venue negatives"
+                       % (best["model"], best["class"],
+                          ("%.0f%%" % (100 * r)) if r is not None else "n/a")}
+    ok = [c for c in retained
+          if c["off_target_mean"] is not None and c["off_target_mean"] <= OFF_TARGET_BAR]
+    if not ok:
+        b = min(retained, key=lambda c: (c["off_target_mean"] if c["off_target_mean"] is not None else 9))
+        w = b["off_target_worst"] or {}
+        return {"decision": "NO MODEL CLEARS BAR", "best_effort": b["model"],
+                "why": "candidates stay quiet on venue footage but are indiscriminate "
+                       "elsewhere: the best (%s) still fires on %.0f%% of off-target control "
+                       "frames at its operating confidence (worst: %.0f%% of %s)"
+                       % (b["model"], 100 * (b["off_target_mean"] or 0),
+                          100 * w.get("rate", 0), w.get("set", "?"))}
+    win = ok[0]
+    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, 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"], _other_controls_clause(win)),
+            "runner_up": ok[1]["model"] if len(ok) > 1 else None}
+
+
+if __name__ == "__main__":
+    main()