@trillboards/edge-sdk 0.2.111 → 0.2.113

package/deploy/detector/bench/regrade_control_selection.py

@@ -37,6 +37,7 @@ from __future__ import annotations
 import argparse
 import json
 import os
+import time
 
 #: 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.
@@ -67,7 +68,124 @@ def rateable_controls(per_control: dict, ctlq: dict) -> dict:
     return out
 
 
-def regrade_capability(cap: dict, ctlq: dict, bar: dict) -> dict:
+#: Schemas this tool will read a NEW control rate out of. A rescore artifact is
+#: the ONLY way a control the original screen never scored can reach a verdict
+#: here, and it is admissible for exactly one reason: it was produced by
+#: `venue_adjudication.py`'s OWN rule -- same GRID, same QUIET_MAX_FIRE, same
+#: worst-valid-bucket quiet_t, same bar -- against a control that carries a
+#: contact-sheet grade. Anything else would be an assertion wearing a filename.
+RESCORE_SCHEMAS = ("trillboards.fire-smoke-rescore/1",)
+
+
+def load_rescores(paths) -> dict:
+    """Committed rescore artifacts, keyed by (model, class).
+
+    Returns {(model, class): row}. A file whose schema is not in
+    `RESCORE_SCHEMAS` is REFUSED rather than skipped: a rescore this tool cannot
+    read is a number somebody expected to count, and silently ignoring it is how
+    a verdict stays stale while looking re-derived.
+    """
+    out = {}
+    for path in paths or []:
+        doc = json.load(open(path))
+        if doc.get("schema") not in RESCORE_SCHEMAS:
+            raise SystemExit(
+                "%s has schema %r, which this tool cannot read (known: %s). Refusing rather "
+                "than skipping -- a rescore that is silently ignored leaves the verdict stale "
+                "while the run reports success."
+                % (path, doc.get("schema"), ", ".join(RESCORE_SCHEMAS)))
+        model = (doc.get("artifact") or {}).get("model_id")
+        if not model:
+            raise SystemExit("%s names no artifact.model_id, so its rates belong to nobody" % path)
+        # A rescore may carry caveats that survive its own verdict -- "this clears
+        # the bar AND no live route reaches it" is one fact, not two, and the
+        # record of record is where a reader decides whether to SELL. Carried
+        # rather than restated so there is one home for the measurement.
+        caveats = doc.get("sellability_caveats") or []
+        for cls, e in (doc.get("per_class") or {}).items():
+            out[(model, cls)] = {
+                "control": e["control_set"],
+                "n": e["control_frames"],
+                "rate_025": e["control_rate_025"],
+                "rate_at_quiet_t": e["control_rate_at_quiet_t"],
+                "quiet_t": e["quiet_t"],
+                "source_file": os.path.basename(path),
+                "sellability_caveats": caveats,
+            }
+    return out
+
+
+def apply_rescore(cand: dict, rescores: dict, ctlq: dict):
+    """Merge a rescored control into one candidate's `per_control`.
+
+    Returns (candidate, note). The candidate is a COPY when anything changed.
+
+    THE OFF-TARGET BOUND IS THE WHOLE CARE HERE. `decide()`'s third gate is
+    `off_target_mean <= bar`, and a rescore does not recompute it -- the
+    off-target control sets the original screen fired against are gone. What it
+    can do is INHERIT the committed value, and only in the direction where that
+    is sound: `off_target` is `(scores >= quiet_t).mean()`, which is monotone
+    NON-INCREASING in the threshold, so a value measured at a LOWER quiet_t is a
+    valid UPPER BOUND at a higher one. If the rescore's threshold is BELOW the
+    committed one the bound runs the wrong way, and the row is refused rather
+    than passed on a number nobody measured at that operating point.
+    """
+    key = (cand.get("model"), cand.get("class"))
+    r = (rescores or {}).get(key)
+    if not r:
+        return cand, None
+    grade = (ctlq.get(r["control"]) or {}).get("grade")
+    if grade is None:
+        raise SystemExit(
+            "rescore %s supplies control %r for %s/%s, which has no contact-sheet grade. "
+            "An ungraded set is neither `unusable` nor `liveness_only`, so it would be "
+            "eligible to carry a verdict on nobody's inspection."
+            % (r["source_file"], r["control"], key[0], key[1]))
+    committed_t = cand.get("quiet_t")
+    if committed_t is not None and r["quiet_t"] < committed_t:
+        return cand, {
+            "model": key[0], "class": key[1], "control": r["control"],
+            "refused": ("rescore quiet_t %s is BELOW the committed %s, so the committed "
+                        "off_target_mean is not an upper bound at the rescored operating "
+                        "point and no off-target number exists for it"
+                        % (r["quiet_t"], committed_t)),
+            "source_file": r["source_file"],
+        }
+    merged = dict(cand)
+    # A RATE BELONGS TO THE THRESHOLD IT WAS MEASURED AT. Raising the candidate's
+    # `quiet_t` does not re-measure the controls already in `per_control` -- their
+    # `rate_at_quiet_t` is still the value at the COMMITTED threshold. Because
+    # `(scores >= t).mean()` is monotone non-increasing in t, that number is an
+    # UPPER BOUND at the higher threshold, so reading it as the recall at the new
+    # operating point OVERSTATES recall and can manufacture a PUBLISH. Every entry
+    # is therefore stamped with the threshold that produced it, and selection
+    # admits only the ones measured at the threshold actually applied.
+    merged["per_control"] = {
+        name: dict(row, measured_at_t=row.get("measured_at_t", committed_t))
+        for name, row in (cand.get("per_control") or {}).items()
+    }
+    merged["per_control"][r["control"]] = {
+        "n": r["n"], "rate_025": r["rate_025"], "rate_at_quiet_t": r["rate_at_quiet_t"],
+        "measured_at_t": r["quiet_t"],
+    }
+    merged["quiet_t"] = r["quiet_t"]
+    note = {
+        "model": key[0], "class": key[1], "control": r["control"], "grade": grade,
+        "n": r["n"], "rate_at_quiet_t": r["rate_at_quiet_t"],
+        "quiet_t_committed": committed_t, "quiet_t_rescored": r["quiet_t"],
+        "off_target_mean_inherited": cand.get("off_target_mean"),
+        "off_target_bound_holds_because": (
+            "off_target is (scores >= t).mean(), monotone non-increasing in t, and the "
+            "rescored t (%s) is >= the committed t (%s), so the committed value is an "
+            "upper bound at the rescored operating point"
+            % (r["quiet_t"], committed_t)),
+        "source_file": r["source_file"],
+        "sellability_caveats": r.get("sellability_caveats") or [],
+    }
+    return merged, note
+
+
+def regrade_capability(cap: dict, ctlq: dict, bar: dict, rescores: dict = None) -> dict:
     """Re-apply the bar to one capability using only rateable controls."""
     recall_bar = bar["recall_retention"]
     off_bar = bar["off_target_mean"]
@@ -88,8 +206,11 @@ def regrade_capability(cap: dict, ctlq: dict, bar: dict) -> dict:
             "why": "resolved before any control is read: %s" % (prior,),
         }
 
-    rows, unknown = [], []
+    rows, unknown, rescored, stale_t = [], [], [], []
     for cand in cap["candidates"]:
+        cand, note = apply_rescore(cand, rescores, ctlq)
+        if note:
+            rescored.append(note)
         elided = "_elided" in (cand.get("by_bucket") or {})
         rate = rateable_controls(cand.get("per_control"), ctlq)
         if not rate:
@@ -120,9 +241,39 @@ def regrade_capability(cap: dict, ctlq: dict, bar: dict) -> dict:
                     "elided": elided,
                 })
             continue
+        # Only a control measured at the threshold this candidate is DECIDED at may
+        # carry the verdict. Absent a rescore nothing is stamped and every control
+        # is at the committed threshold, so this is a no-op on the untouched path.
+        applied_t = cand.get("quiet_t")
+        fresh = {k: v for k, v in rate.items()
+                 if v.get("measured_at_t") is None or v["measured_at_t"] == applied_t}
+        stale = {k: v for k, v in rate.items() if k not in fresh}
+        for k, v in sorted(stale.items()):
+            stale_t.append({
+                "model": cand["model"], "class": cand["class"], "control": k,
+                "measured_at_t": v.get("measured_at_t"), "applied_t": applied_t,
+                "rate_at_measured_t": v.get("rate_at_quiet_t"),
+                "why_excluded": ("its rate is an upper bound at the applied threshold, "
+                                 "not a measurement of it, so it may not carry a verdict"),
+            })
+        if not fresh:
+            unknown.append({
+                "model": cand["model"], "class": cand["class"],
+                "decided_on": cand.get("best_control"),
+                "grade": (ctlq.get(cand.get("best_control")) or {}).get("grade"),
+                "why_unknown": ("a rescore moved quiet_t to %s and every rateable control "
+                                "here was measured at a lower threshold (%s), where its rate "
+                                "is only an upper bound -- no control has a rate AT the "
+                                "applied operating point"
+                                % (applied_t,
+                                   ", ".join(sorted(str(v.get("measured_at_t"))
+                                                    for v in stale.values())))),
+                "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]
+        name = max(fresh, key=lambda k: (fresh[k]["rate_025"] or 0))
+        row = fresh[name]
         rows.append({
             "model": cand["model"], "class": cand["class"],
             "control": name, "control_n": row["n"], "grade": row["grade"],
@@ -130,8 +281,13 @@ def regrade_capability(cap: dict, ctlq: dict, bar: dict) -> dict:
             "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"]}
+            "also_scored": {k: dict(
+                                {"n": v["n"], "grade": (ctlq.get(k) or {}).get("grade"),
+                                 "rate_at_quiet_t": v["rate_at_quiet_t"]},
+                                **({} if v.get("measured_at_t") in (None, applied_t) else {
+                                    "measured_at_t": v["measured_at_t"],
+                                    "upper_bound_only": ("measured at %s, not the applied %s"
+                                                         % (v["measured_at_t"], applied_t))}))
                             for k, v in (cand.get("per_control") or {}).items() if k != name},
             "source": "recomputed from committed per_control",
         })
@@ -208,6 +364,10 @@ def regrade_capability(cap: dict, ctlq: dict, bar: dict) -> dict:
         "winner": win,
         "candidates_regraded": len(rows),
         "candidates_unknown": blocking,
+        "rescored_controls": rescored,
+        # Never silent: a control dropped for being measured at another
+        # threshold is a stated exclusion, exactly like a withheld model.
+        "stale_threshold_controls": stale_t,
     }
 
 
@@ -260,7 +420,35 @@ def _selftest() -> None:
     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")
+    # 3. A RESCORE SETTLES AN UNRESOLVED. This is the whole point of --rescore: a
+    #    control added after the screen ran reaches the ladder, and a candidate
+    #    that clears the bar on it turns "not known" into PUBLISH. The elided row
+    #    is still unknown and still reported -- it just cannot block any more,
+    #    which is this tool's own stated monotonicity ("an unknown can only ever
+    #    ADD a passing candidate").
+    ctlq3 = dict(ctlq, fresh={"grade": "good"})
+    rescore = {("m1", "fire"): {"control": "fresh", "n": 72, "rate_025": 0.82,
+                                "rate_at_quiet_t": 0.86, "quiet_t": 0.30,
+                                "source_file": "rescore.json"}}
+    settled = regrade_capability(cap(UNRESOLVED), ctlq3, bar, rescore)
+    assert settled["regraded_decision"] == "PUBLISH", settled["regraded_decision"]
+    assert settled["winner"]["control"] == "fresh", settled["winner"]
+    assert settled["rescored_controls"], "the rescore must be recorded, not silently used"
+    assert settled["changed"] is True
+
+    # 4. A RESCORE AT A LOWER THRESHOLD IS REFUSED. `off_target_mean` is inherited
+    #    from the committed row and is only an UPPER BOUND when the rescored
+    #    threshold is >= the committed one. Below it, no off-target number exists
+    #    at that operating point and passing the row would assert one.
+    low = {("m1", "fire"): {"control": "fresh", "n": 72, "rate_025": 0.82,
+                            "rate_at_quiet_t": 0.86, "quiet_t": 0.10,
+                            "source_file": "rescore.json"}}
+    refused = regrade_capability(cap(UNRESOLVED), ctlq3, bar, low)
+    assert refused["regraded_decision"] == UNRESOLVED, refused["regraded_decision"]
+    assert any("refused" in r for r in refused["rescored_controls"]), refused["rescored_controls"]
+
+    print("selftest OK: idempotent on UNRESOLVED; a measured failure is left alone; "
+          "a rescore settles an unknown; a rescore below the committed threshold is refused")
 
 
 def main() -> None:
@@ -269,7 +457,24 @@ def main() -> None:
         _selftest()
         return
     ap.add_argument("--adjudication", required=True)
-    ap.add_argument("--control-quality", required=True)
+    ap.add_argument("--control-quality", required=True, nargs="+",
+                    help="positive-control-quality-*.json. TAKES A LIST and merges them, later "
+                         "files winning, exactly as venue_adjudication.py does. It read ONE "
+                         "path until 2026-08-27, which is unsafe for the reason that file "
+                         "states about itself: `liveness_only` and `unusable` are both built "
+                         "by MEMBERSHIP, so a set whose grade lives in a file this run did not "
+                         "read falls through both and is eligible to carry a verdict on "
+                         "nobody's inspection. The grades live in DATED files because 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 -- "
+                         "which means a single-path reader was guaranteed to go stale.")
+    ap.add_argument("--rescore", nargs="+", default=None,
+                    help="committed rescore artifact(s) supplying a control the ORIGINAL "
+                         "screen never scored. Admissible only because they are produced by "
+                         "venue_adjudication.py's own rule -- same GRID, same QUIET_MAX_FIRE, "
+                         "same worst-valid-bucket quiet_t, same bar. Without this there is no "
+                         "path for a control added after the screen ran, and a capability "
+                         "whose verdict a later measurement settles stays UNRESOLVED for ever.")
     ap.add_argument("--out", required=True)
     ap.add_argument("--apply", action="store_true",
                     help="also write the corrected verdict back into --adjudication. The "
@@ -278,10 +483,15 @@ def main() -> None:
     args = ap.parse_args()
 
     adj = json.load(open(args.adjudication))
-    ctlq = json.load(open(args.control_quality))
+    ctlq = {}
+    for _q in args.control_quality:
+        for _k, _v in json.load(open(_q)).items():
+            if isinstance(_v, dict) and isinstance(_v.get("grade"), str):
+                ctlq[_k] = _v
     bar = adj["bar"]
 
-    rows = [regrade_capability(c, ctlq, bar) for c in adj["capabilities"]]
+    rescores = load_rescores(args.rescore)
+    rows = [regrade_capability(c, ctlq, bar, rescores) 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
@@ -313,6 +523,8 @@ def main() -> None:
                          "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.",
+        "control_quality_inputs": sorted(os.path.basename(x) for x in args.control_quality),
+        "rescore_inputs": sorted({os.path.basename(x) for x in (args.rescore or [])}),
         "liveness_only_grades": list(LIVENESS_ONLY_GRADES),
         "unusable_grades": list(UNUSABLE_GRADES),
         "bar": bar,
@@ -327,34 +539,85 @@ def main() -> None:
     }, open(args.out, "w"), indent=1)
 
     if args.apply and changed:
+        # THE WRITER MUST HANDLE BOTH DIRECTIONS. It was built for the WITHDRAWAL
+        # only -- it hardcoded the date `2026-08-26`, always wrote `ships: False`,
+        # and never recorded a winner, because a withdrawal has none. All three
+        # are correct for taking a PUBLISH away and wrong for giving one back,
+        # and a restoration written through the withdrawal's fields would land a
+        # PUBLISH in the record with no model, no control and `ships: False`
+        # beside it -- a verdict a reader cannot act on and a sales claim nobody
+        # can trace to an artifact.
+        today = time.strftime("%Y-%m-%d", time.gmtime())
         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"] = {
+            win = r.get("winner") or {}
+            publishes = r["regraded_decision"] == "PUBLISH"
+            if publishes:
+                why_corrected = (
+                    "a control that CAN rate this class was added after the screen ran "
+                    "(`%s`, n=%s, grade %s) and is committed in %s, which computed its rate "
+                    "with venue_adjudication.py's OWN rule -- same GRID, same QUIET_MAX_FIRE, "
+                    "same worst-valid-bucket quiet_t, same bar. Re-applying that bar with the "
+                    "new control in scope clears it. The elided rows stay unknown and cannot "
+                    "block: an unknown can only ever ADD a passing candidate."
+                    % (win.get("control"), win.get("control_n"), win.get("grade"),
+                       ", ".join(sorted({os.path.basename(x) for x in (args.rescore or [])}))
+                       or "a rescore artifact"))
+            else:
+                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")))
+            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.
+                # NOT re-derived here in either direction, and for the same
+                # reason: `events_lost` / `vlm_calls_saved` are computed by
+                # venue_adjudication.py from the FULL per-frame score matrices
+                # against the whole negative set, which this tool does not hold.
+                # A withdrawal must not keep a promise computed from a recall it
+                # no longer accepts; a restoration must not invent one.
                 "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,
-                },
+                "gate_is_null_because": (
+                    "the cascade-gate arithmetic is a function of the full score matrices, "
+                    "which this tool does not read. A verdict is derivable from committed "
+                    "rates; a savings promise is not."),
+            }
+            caveats = [c for n in (r.get("rescored_controls") or [])
+                       for c in (n.get("sellability_caveats") or [])]
+            if caveats:
+                # TOP LEVEL, beside the verdict, not buried in `corrected`. This
+                # file is quoted in the sales claim sheet, and a PUBLISH whose
+                # caveat is one level down is a PUBLISH that gets quoted alone.
+                decision["sellability_caveats"] = caveats
+            if publishes:
+                decision.update({
+                    "model": win.get("model"),
+                    "class": win.get("class"),
+                    "control": win.get("control"),
+                    "control_n": win.get("control_n"),
+                    "control_grade": win.get("grade"),
+                    "operating_conf": win.get("quiet_t"),
+                    "n_valid_negatives": win.get("n_valid_negatives"),
+                    "also_scored": win.get("also_scored"),
+                })
+            decision["corrected"] = {
+                "on": today,
+                "by": "deploy/detector/bench/regrade_control_selection.py --apply",
+                "was": was,
+                "ships": publishes,
+                "why_corrected": why_corrected,
+                "needs_remeasure": r["candidates_unknown"],
+                "rescored_controls": r.get("rescored_controls") or [],
+                "regrade_artifact": args.out,
             }
+            cap["decision"] = decision
             cap["changed"] = bool(cap.get("prior_decision_taxi_negatives")
                                   and cap["prior_decision_taxi_negatives"]
                                   != r["regraded_decision"])

package/deploy/detector/bench/venue_adjudication.py

@@ -151,8 +151,19 @@ CLASS_CONTROL = {
     "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"],
+    "door": ["n_door"], "window": ["n_window"],
+    # `phone_use_meva` (22 frames / 17 fixed cameras, `good`) leads because it is the only
+    # set that can rate this class at all TODAY: `n_phone` is graded `good` but its FRAMES
+    # ARE GONE -- s3://trillboards-media-prod/DEV/regression-corpus/ holds no `n_phone`
+    # prefix, measured 2026-08-27, the same as fire_cctv/fire_generic/wc_spill. `n_phone` is
+    # KEPT and stays second for the same reason `fire_generic` was kept after it was
+    # demoted: its number is in the committed adjudication and deleting the mapping would
+    # hide what the earlier screen scored. The two also answer different questions --
+    # `n_phone` is web stills of people holding smartphones, `phone_use_meva` is fixed CCTV
+    # at 79-690 px of person height, which is the deployment.
+    "phone": ["phone_use_meva", "n_phone"], "cell phone": ["phone_use_meva", "n_phone"],
+    "phone_call": ["phone_use_meva", "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"],

package/deploy/detector/tests/test_regrade_control_selection.py

@@ -29,7 +29,10 @@ sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent / "bench")
 
 from regrade_control_selection import (  # noqa: E402
     PRESERVE_ON_BLOCKING,
+    RESCORE_SCHEMAS,
     UNRESOLVED,
+    apply_rescore,
+    load_rescores,
     rateable_controls,
     regrade_capability,
 )
@@ -116,5 +119,110 @@ class TestRegradeControlSelection(unittest.TestCase):
             self.assertEqual(out["status"], "not_affected")
 
 
+
+
+class RescoreReachesTheLadder(unittest.TestCase):
+    """A control added AFTER the screen ran must be able to settle a verdict.
+
+    Without this the tool has no input for a set the original run never scored,
+    so a capability whose verdict a later measurement settles stays `UNRESOLVED`
+    for ever while the registry publishes a model — two stores disagreeing about
+    whether a capability is sellable, which is the state this input exists to
+    end. Proved empirically first: with `fire_firesense` graded `good` and
+    visible to it, the tool still returned UNRESOLVED, because the new control
+    appears in no candidate's `per_control`.
+    """
+
+    RESCORE = {("m1", "fire"): {"control": "fresh", "n": 72, "rate_025": 0.82,
+                                "rate_at_quiet_t": 0.86, "quiet_t": 0.30,
+                                "source_file": "rescore.json"}}
+    CTLQ3 = dict(CTLQ, fresh={"grade": "good"})
+
+    def test_a_rescore_settles_an_unresolved(self):
+        r = regrade_capability(_cap(UNRESOLVED), self.CTLQ3, BAR, self.RESCORE)
+        self.assertEqual(r["regraded_decision"], "PUBLISH")
+        self.assertEqual(r["winner"]["control"], "fresh")
+        self.assertTrue(r["rescored_controls"], "the rescore must be recorded, not silently used")
+
+    def test_a_rescore_below_the_committed_threshold_is_REFUSED(self):
+        """`off_target_mean` is INHERITED, and only bounds upward.
+
+        It is `(scores >= t).mean()`, monotone non-increasing in t, so a value
+        measured at a LOWER threshold is an upper bound at a higher one. Below
+        the committed threshold the bound runs the wrong way and there is no
+        off-target number at that operating point — passing the row would assert
+        one nobody measured.
+        """
+        low = {("m1", "fire"): dict(self.RESCORE[("m1", "fire")], quiet_t=0.10)}
+        r = regrade_capability(_cap(UNRESOLVED), self.CTLQ3, BAR, low)
+        self.assertEqual(r["regraded_decision"], UNRESOLVED)
+        self.assertTrue(any("refused" in n for n in r["rescored_controls"]))
+
+    def test_an_ungraded_rescored_control_is_refused_not_trusted(self):
+        """An ungraded set falls through both `liveness_only` and `unusable`."""
+        with self.assertRaises(SystemExit):
+            apply_rescore(_cap(UNRESOLVED)["candidates"][0], self.RESCORE, CTLQ)
+
+    def test_a_rescore_never_overturns_a_measured_failure_into_silence(self):
+        """A passing rescore may raise a failure to PUBLISH — that is the point —
+        but it must do so through the ladder, with a winner and a recorded source."""
+        r = regrade_capability(_cap("NO MODEL CLEARS BAR"), self.CTLQ3, BAR, self.RESCORE)
+        self.assertEqual(r["regraded_decision"], "PUBLISH")
+        self.assertEqual(r["rescored_controls"][0]["source_file"], "rescore.json")
+
+    def test_an_unreadable_rescore_schema_is_refused_not_skipped(self):
+        import json as _json
+        import tempfile
+        with tempfile.NamedTemporaryFile("w", suffix=".json", delete=False) as fh:
+            _json.dump({"schema": "something.else/1"}, fh)
+            bad = fh.name
+        with self.assertRaises(SystemExit):
+            load_rescores([bad])
+
+    def test_a_stale_threshold_control_may_not_carry_the_verdict(self):
+        """THE RATE BELONGS TO THE THRESHOLD IT WAS MEASURED AT.
+
+        A rescore raises the candidate's `quiet_t` but re-measures only its OWN
+        control. Every other rate in `per_control` is still the value at the
+        committed, LOWER threshold, where `(scores >= t).mean()` is an UPPER
+        BOUND — so reading it as the recall at the new operating point overstates
+        recall. Here `big` is stale at 0.90 and the rescored control is a genuine
+        0.30 failure: without per-control threshold tracking `argmax(rate_025)`
+        picks `big` and manufactures a PUBLISH out of a number measured somewhere
+        else.
+        """
+        cap = _cap(UNRESOLVED, with_elided=False)
+        cap["candidates"][0]["per_control"]["big"] = {
+            "n": 9, "rate_025": 0.90, "rate_at_quiet_t": 0.90}
+        weak = {("m1", "fire"): dict(self.RESCORE[("m1", "fire")],
+                                     rate_025=0.30, rate_at_quiet_t=0.30)}
+        r = regrade_capability(cap, self.CTLQ3, BAR, weak)
+        self.assertNotEqual(
+            r["regraded_decision"], "PUBLISH",
+            "a rate measured at the committed threshold was used to clear the bar "
+            "at the higher rescored threshold")
+        stale = r["stale_threshold_controls"]
+        self.assertTrue(stale, "the stale-threshold refusal must be stated, not silent")
+        self.assertEqual(stale[0]["control"], "big")
+        self.assertEqual((stale[0]["measured_at_t"], stale[0]["applied_t"]), (0.25, 0.30))
+
+    def test_a_control_at_the_applied_threshold_still_carries_the_verdict(self):
+        """The positive half: the rescored control IS at the applied threshold,
+        so it decides — this is the path fire and smoke actually take."""
+        r = regrade_capability(_cap(UNRESOLVED, with_elided=False),
+                               self.CTLQ3, BAR, self.RESCORE)
+        self.assertEqual(r["regraded_decision"], "PUBLISH")
+        self.assertEqual(r["winner"]["control"], "fresh")
+
+    def test_without_a_rescore_no_control_is_stamped_stale(self):
+        """The untouched path must be byte-identical — nothing is stamped, so
+        every control remains admissible."""
+        a = regrade_capability(_cap("NO MODEL CLEARS BAR", rateable_rate=0.8), CTLQ, BAR)
+        self.assertEqual(a["regraded_decision"], "PUBLISH")
+
+    def test_the_known_schema_list_is_not_empty(self):
+        self.assertTrue(RESCORE_SCHEMAS)
+
+
 if __name__ == "__main__":
     unittest.main()

package/dist/AudienceAnalyzeClient.d.ts

@@ -210,6 +210,17 @@ export declare class AudienceAnalyzeClient {
          * local-vlm rows while the cloud path is 100%.
          */
         promptText?: string;
+        /**
+         * Which fields of `preAnalyzed` a GRANTED SPECIALIST answered, as
+         * `field -> modelId`. Everything not named here was answered by the
+         * on-device VLM.
+         *
+         * The two producers write byte-identical values into the same flat
+         * object, so this map is the only thing that can separate them — and the
+         * server needs it to stamp `local_detector` in `_provenance_map` rather
+         * than flattening the whole observation to `local_connector`.
+         */
+        detectorProduced?: Record<string, string>;
     }): Promise<AudienceAnalyzeResponse>;
     /**
      * POST a FRAMELESS camera-health beacon. This is used when the connector can

package/dist/AudienceAnalyzeClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AudienceAnalyzeClient.d.ts","sourceRoot":"","sources":["../src/AudienceAnalyzeClient.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"AudienceAnalyzeClient.d.ts","sourceRoot":"","sources":["../src/AudienceAnalyzeClient.ts"],"names":[],"mappings":"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"}

package/dist/AudienceAnalyzeClient.js

@@ -230,6 +230,13 @@ class AudienceAnalyzeClient {
             ...(typeof request.promptText === 'string' && request.promptText.trim() !== ''
                 ? { localPromptText: request.promptText }
                 : {}),
+            // Per-field producer attribution. Sent only when a specialist actually
+            // answered something: an absent key means "no specialist answered on this
+            // frame", which is a different fact from an empty map and the server
+            // treats them the same way only because it never sees the second one.
+            ...(request.detectorProduced && Object.keys(request.detectorProduced).length > 0
+                ? { detectorProduced: request.detectorProduced }
+                : {}),
             // Same last-spread override semantics as analyze(); see the note there.
             ...(request.extra || {}),
             ...(evidenceId ? { evidenceId } : {}),