Compare commits

..

No commits in common. 'feature/unknown-r3-server-integration' and 'main' have entirely different histories.

11
.gitattributes vendored

@ -1,11 +0,0 @@
/ptz_tracker_modular/alarm_boundary.py text eol=lf
/ptz_tracker_modular/alarm_eligibility.py text eol=lf
/ptz_tracker_modular/frame_time.py text eol=lf
/ptz_tracker_modular/inspection_bridge.py text eol=lf
/ptz_tracker_modular/inspection_handoff.py text eol=lf
/ptz_tracker_modular/inspection_input.py text eol=lf
/ptz_tracker_modular/inspection_runtime.py text eol=lf
/ptz_tracker_modular/model_class_contract.py text eol=lf
/ptz_tracker_modular/unknown_inspection.py text eol=lf
/ptz_tracker_modular/inspection_startup.py text eol=lf
/integration/unknown_r3/server.patch text eol=lf -whitespace

@ -1,24 +0,0 @@
# UNKNOWN R3
Этот пакет предназначен для офлайн-проверки на снимке кода объекта. Ветка `main` содержит другую версию контроллера. Патч привязан к шести файлам снимка от 9 ноября 2026 года и проверяет SHA-256 входных и выходных файлов. Входной `streaming.py` должен быть снят с фактического Docker bind. Исправление prezoom retention в этот пакет не входит.
## Проверка копии
```sh
python -B integration/unknown_r3/build_review_copy.py /path/to/server-source /path/to/new-review-copy
cd /path/to/new-review-copy
python -B test_handoff.py
python -B test_alarm_transport.py
python -B test_composition.py
python -B test_server_path.py
```
Нужны Python 3.11 или новее, Git, NumPy и requests для тестового окружения. Тесты подменяют WebSocket, HTTP, инференс и управление. Последний тест использует локальный цикл событий asyncio и проходит через реальные функции декодера и очереди.
## Поведение
Детектор класса `airborne_object` даёт геометрию для центровки и ограниченного зума до определения класса. Кадр сохраняет время локального декодирования, последовательность, источник и владельца при проходе через очередь и OSTrack. Классификатор обрабатывает кропы отдельно. Решение о тревоге требует свежего независимого подтверждения БПЛА на двух кадрах и повторной проверки при отправке. Птица и пилотируемый самолёт не дают тревогу.
`UNKNOWN_INSPECTION_ENABLE` по умолчанию выключен. Для запуска нужны проверенные локальные `.pt` веса двух моделей, `UNKNOWN_INSPECTION_SETTINGS`, список PTZ `UNKNOWN_INSPECTION_CAMERAS`, пути `UNKNOWN_INSPECTION_PROPOSAL_PATH` и `UNKNOWN_INSPECTION_CLASSIFIER_PATH`, а также доверенные функции допуска `UNKNOWN_INSPECTION_AUTHORIZE(camera, owner)` и оценки перекрытия `UNKNOWN_INSPECTION_OCCLUDED(camera, stamp, frame, bbox)`. Функция оценки возвращает `False` только при подтверждённой видимости. Отсутствующая или неопределённая оценка не даёт семантического подтверждения.
Режим ограничен прямым обнаружением в разрешённых PTZ-потоках. Обзорные потоки сохраняют предпросмотр. Для передачи цели с обзорной камеры нужен отдельный проверенный путь. Физическая скорость, устойчивое удержание и итоговая классификация на объекте требуют испытаний с готовыми весами и измерениями на камерах.

@ -1,52 +0,0 @@
"""Build an offline review copy from an exact server source snapshot."""
import argparse
import hashlib
import json
from pathlib import Path
import shutil
import subprocess
BUNDLE = Path(__file__).resolve().parent
REPO = BUNDLE.parent.parent
def sha(path):
with path.open("rb") as file:
return hashlib.file_digest(file, "sha256").hexdigest()
def check(directory, expected):
for name, digest in expected.items():
path = directory / name
if not path.is_file() or sha(path) != digest:
raise ValueError(f"SHA256 mismatch or missing file: {name}")
def build(source, destination):
manifest = json.loads((BUNDLE / "pins.json").read_text(encoding="utf-8"))
check(source, manifest["source"])
check(REPO / "ptz_tracker_modular", manifest["modules"])
check(BUNDLE, {"server.patch": manifest["patch_sha256"]})
destination.mkdir()
package = destination / "ptz_tracker_modular"
package.mkdir()
for name in manifest["source"]:
shutil.copyfile(source / name, package / name)
for name in manifest["modules"]:
shutil.copyfile(REPO / "ptz_tracker_modular" / name, package / name)
patch = str(BUNDLE / "server.patch")
subprocess.run(["git", "-c", "core.autocrlf=false", "apply", "--check", patch], cwd=destination, check=True)
subprocess.run(["git", "-c", "core.autocrlf=false", "apply", patch], cwd=destination, check=True)
check(package, manifest["result"])
for path in (BUNDLE / "tests").glob("test_*.py"):
shutil.copyfile(path, destination / path.name)
print(f"Verified offline copy: {destination}")
if __name__ == "__main__":
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("source", type=Path, help="directory containing exact server source files")
parser.add_argument("destination", type=Path, help="new local output directory")
args = parser.parse_args()
build(args.source.resolve(), args.destination.resolve())

@ -1,31 +0,0 @@
{
"source": {
"alarms.py": "f71d75f34664f48ffc230d54f3ee10168ad1d7f7942fbe815bc319d2764701ca",
"events.py": "c6606f18fdb17df59fbe74f38a500c0a0c0a9e7c8989bab9cf13685a726c8c53",
"main.py": "d1da4c165a89ff86713be8e940fd86cef84276250bb9f08ef42cfb8c8038618a",
"postprocess.py": "5326c9d3093b7c863310b9c0a7a85010a1a83ff014631a054ac9a16cc31c8fc5",
"streaming.py": "313828be8be66a5ebbf2365ec91de965128f06da16c54ff2332733a0e2fc701c",
"visual_control_probe.py": "a5d6608c0fefa316a48384685ddf9b35bcd7dc1a5f7b1f8f1b348490d448832f"
},
"result": {
"alarms.py": "6faf903aa6d538cb7edabbc6a065ed9190d45f8b59f4e9efb9c9b3cd8ae349e5",
"events.py": "f002025c393025b7ebec63ef2af94326322d5153b70ecc896961d48dba961cdb",
"main.py": "b703db6509979f8ec4f736a994dbded6726ea590249e5f4ad381bdf79e38c5aa",
"postprocess.py": "d88802a44cfbf2658ea8d6fc85c689a8e72369815205db4df68a13690b850495",
"streaming.py": "f4debcda1e995eb5e6c56e30b8da027c0020fe9e5ea80b150fde12290fda4ec9",
"visual_control_probe.py": "6d81759060646a4af08d5d0de49ebad7ac417e1a789e37eff2403fff6d2162c9"
},
"modules": {
"alarm_boundary.py": "c7ca0150f284375cef1129ecbbb5bffa91bb84e0a09e25483a3f90a579c28713",
"alarm_eligibility.py": "b0de51051bff969f590b0eee91a62a2456c4cf66e733231cdd545525249d3f48",
"frame_time.py": "c9d64814c54383b94299f78b1255e5f50715b25ef6c3aff7197bc8fa78a0884b",
"inspection_bridge.py": "bb8663293b36002902dbfef1f63b40ff7a9e7dea7147088305f1332a91ad37f9",
"inspection_handoff.py": "c714d69b24fde86653ab8613e9518fd689fa3691f129421068f3bb975f44e246",
"inspection_input.py": "324562a7deacb3abdb5c536263dfa104f149c6157306bb792beea318d7226db1",
"inspection_runtime.py": "1eaee1021d43d1814d2c48881df90eab227e5d2bae4744c379eccfa5b169694d",
"model_class_contract.py": "93ebdc13602e757ac24bf35e10698c4a19fd9fa4ca8bd4f0fef850b099edef2f",
"unknown_inspection.py": "ff799622ae45d91b745cc345c7a3ed3495cae88a29df9ca49ac7dbc5fe8933bd",
"inspection_startup.py": "9d9f901f4ee953e5efdbbf975a0c14413cdf17e9a1e6cd22b6d6f2135a81d74a"
},
"patch_sha256": "fbb76f3fce454702016fa5416e00e09cefff9e59afa3fc6eca57d81aa7cbf4da"
}

@ -1,896 +0,0 @@
--- a/ptz_tracker_modular/alarms.py
+++ b/ptz_tracker_modular/alarms.py
@@ -10,2 +10,3 @@
import threading
+from itertools import count
from datetime import datetime, timezone
@@ -29,2 +30,7 @@
cameras_io = None # type: ignore
+
+try:
+ from . import alarm_boundary as _boundary
+except ImportError:
+ import alarm_boundary as _boundary
@@ -81,2 +87,3 @@
_http_queue: Optional[asyncio.Queue] = None
+_http_revisions = count(1)
def _ensure_http_queue() -> asyncio.Queue:
@@ -266,3 +273,3 @@
online = bool(cam_id in detected)
- armed = bool((_H.get(cam_id) or {}).get("armed", False))
+ armed = is_armed(cam_id)
cameras_payload.append(_build_swagger_camera(mac_n, alarm=armed, status=online))
@@ -277,3 +284,16 @@
+def _camera_for_mac(mac):
+ try:
+ normalized = _norm_mac(mac)
+ found = [int(c) for c in config.CAMERA_CONFIG if _get_cam_mac(int(c)) == normalized]
+ return found[0] if len(found) == 1 else None
+ except Exception:
+ return None
+
+
def _dispatch_ws(minimal: Dict[str, Any]) -> None:
+ if _boundary.enabled():
+ minimal = {**minimal, "_cc10_contexts": _boundary.capture_contexts(config.CAMERA_CONFIG)}
+ token = minimal["_cc10_contexts"]
+ minimal = {**_boundary.filter_ws(minimal), "_cc10_contexts": token}
q = _ensure_ws_queue()
@@ -291,3 +311,6 @@
loop = _state.MAIN_LOOP
- item = {"url": url, "json": body}
+ # Keep the original ordering when a failed snapshot is retried later.
+ contexts = _boundary.capture_contexts(config.CAMERA_CONFIG)
+ item = {"url": url, "json": _boundary.filter_http(body, contexts, _camera_for_mac),
+ "_created_at": next(_http_revisions), "_cc10_contexts": contexts}
if loop is not None:
@@ -316,3 +339,3 @@
"""Публичный геттор текущего состояния тревоги (armed) по камере."""
- return bool((_H.get(int(cam_idx)) or {}).get("armed", False))
+ return bool((_H.get(int(cam_idx)) or {}).get("armed", False)) and _boundary.arm_allowed(int(cam_idx))
@@ -332,2 +355,3 @@
"""
+ detected = bool(detected) and _boundary.arm_allowed(cam_idx)
changed = False
@@ -335,2 +359,4 @@
st = _hyst_state(cam_idx)
+ if _boundary.enabled() and not detected:
+ st["off"] = ALARM_COUNT_OFF
if detected:
@@ -347,3 +373,3 @@
changed = True
- aggregate_alarm = any(bool(v.get("armed", False)) for v in _H.values())
+ aggregate_alarm = any(is_armed(c) for c in _H)
@@ -383,2 +409,4 @@
return
+
+ alarm = bool(alarm) and _boundary.arm_allowed(_camera_for_mac(mac_n))
@@ -465,3 +493,4 @@
- data_bit = bool(last.get("data", False)) if isinstance(last, dict) else bool(last)
+ guarded_last = _boundary.filter_ws(last)
+ data_bit = bool(guarded_last.get("data", False)) if isinstance(guarded_last, dict) else bool(guarded_last)
to_send = {"type": "video_alarm", "data": data_bit}
@@ -489,2 +518,9 @@
+def _http_error_detail(response: Any) -> str:
+ detail = str(response.text or "")
+ if ALARM_HTTP_API_KEY:
+ detail = detail.replace(ALARM_HTTP_API_KEY, "[redacted]")
+ return " ".join(detail.split())[:500]
+
+
async def alarm_http_sender() -> None:
@@ -499,22 +535,6 @@
from requests.adapters import HTTPAdapter
- try:
- from urllib3.util.retry import Retry # type: ignore
- except Exception:
- Retry = None # type: ignore
-
sess = requests.Session()
sess.trust_env = False
- if Retry is not None:
- adapter = HTTPAdapter(
- pool_connections=16,
- pool_maxsize=16,
- max_retries=Retry(
- total=2,
- backoff_factor=0.3,
- status_forcelist=[500, 502, 503, 504],
- raise_on_status=False,
- ),
- )
- else:
- adapter = HTTPAdapter(pool_connections=16, pool_maxsize=16, max_retries=0)
+ # One retry policy owns POST attempts; do not multiply transport retries.
+ adapter = HTTPAdapter(pool_connections=16, pool_maxsize=16, max_retries=0)
sess.mount("http://", adapter)
@@ -527,7 +547,20 @@
- def _merge_http_bucket(bucket: List[Dict[str, Any]]) -> Tuple[str, Dict[str, Any]]:
- # Все элементы в bucket — с одинаковым URL. Берём ПОСЛЕДНИЙ body.
- url = bucket[0].get("url", "")
- last_body = bucket[-1].get("json") or {}
- return url, last_body
+ latest_by_url: Dict[str, int] = {}
+ max_retries = max(0, min(5, int(getattr(config, "ALARM_HTTP_MAX_RETRIES", 2))))
+ retry_base = max(0.0, float(getattr(config, "ALARM_HTTP_RETRY_BASE_SEC", 1.0)))
+
+ async def retry_failed(failed: Dict[str, Any], response: Any = None) -> None:
+ attempts = int(failed.get("_retries", 0))
+ if attempts >= max_retries:
+ logger.error("[ALARM][HTTP-BULK][RETRY-EXHAUSTED] url=%s attempts=%d; waiting for fresh state",
+ failed.get("url", ""), attempts + 1)
+ return
+ delay = min(8.0, retry_base * (2 ** attempts))
+ if response is not None:
+ try:
+ delay = max(delay, min(30.0, float(response.headers.get("Retry-After", 0))))
+ except (ValueError, TypeError, AttributeError):
+ pass
+ await asyncio.sleep(delay)
+ q.put_nowait({**failed, "_retries": attempts + 1})
@@ -535,4 +568,6 @@
item = await q.get()
- try:
- bucket = [item]
+ item.setdefault("_created_at", next(_http_revisions))
+ selected = item
+ bucket = [item]
+ try:
t0 = asyncio.get_running_loop().time()
@@ -541,2 +576,3 @@
nxt = q.get_nowait()
+ nxt.setdefault("_created_at", next(_http_revisions))
if nxt.get("url") != bucket[0].get("url"):
@@ -550,3 +586,7 @@
- url_raw, body = _merge_http_bucket(bucket)
+ # A retry can be queued behind a newer alarm OFF. Queue position
+ # must never make an old ON overwrite that newer observation.
+ _, selected = max(enumerate(bucket), key=lambda pair: (pair[1]["_created_at"], pair[0]))
+ url_raw = selected.get("url", "")
+ body = selected.get("json") or {}
base = _sanitize_http_base(ALARM_HTTP_BASE)
@@ -559,2 +599,7 @@
+ revision = selected["_created_at"]
+ if revision < latest_by_url.get(url, 0):
+ continue
+ latest_by_url[url] = revision
+
cams_cnt = len(body.get("cameras") or [])
@@ -563,3 +608,3 @@
def _post():
- return sess.post(url, json=body, headers=headers, timeout=3.0, verify=verify_arg)
+ return sess.post(url, json=_boundary.filter_http(body, selected.get("_cc10_contexts"), _camera_for_mac), headers=headers, timeout=3.0, verify=verify_arg)
@@ -569,15 +614,11 @@
else:
- logger.warning("[ALARM][HTTP-BULK][FAIL] %s HTTP %s", url, resp.status_code)
- logger.debug("[ALARM][HTTP-BULK][RESP] %s", (resp.text or "")[:200])
- # вернуть последний элемент на ретрай
- try:
- q.put_nowait(bucket[-1])
- except Exception:
- pass
+ logger.warning("[ALARM][HTTP-BULK][FAIL] %s HTTP %s response=%s",
+ url, resp.status_code, _http_error_detail(resp))
+ if resp.status_code in (408, 429) or 500 <= resp.status_code < 600:
+ await retry_failed(selected, resp)
+ # Repeating an unchanged 400/401/403/404/422 cannot repair it.
+ # A fresh event or periodic heartbeat may still be delivered.
except Exception as exc:
logger.error("[ALARM][HTTP-BULK] error: %s", exc)
- try:
- q.put_nowait(item)
- except Exception:
- pass
+ await retry_failed(selected)
finally:
@@ -627,3 +668,3 @@
sess.trust_env = False
- if Retry is not None:
+ if Retry is not None and not _boundary.enabled():
adapter = HTTPAdapter(
@@ -688,2 +729,3 @@
body = _build_swagger_payload(cameras)
+ contexts = _boundary.capture_contexts(config.CAMERA_CONFIG)
cams_cnt = len(cameras)
@@ -692,3 +734,3 @@
def _post():
- return sess.post(url, json=body, headers=headers, timeout=3.0, verify=verify_arg)
+ return sess.post(url, json=_boundary.filter_http(body, contexts, _camera_for_mac), headers=headers, timeout=3.0, verify=verify_arg)
@@ -698,4 +740,4 @@
else:
- logger.warning("[ALARM][HEARTBEAT][FAIL] %s HTTP %s", url, resp.status_code)
- logger.debug("[ALARM][HEARTBEAT][RESP] %s", (resp.text or "")[:200])
+ logger.warning("[ALARM][HEARTBEAT][FAIL] %s HTTP %s response=%s",
+ url, resp.status_code, _http_error_detail(resp))
else:
--- a/ptz_tracker_modular/events.py
+++ b/ptz_tracker_modular/events.py
@@ -11,3 +11,3 @@
-from . import config, state
+from . import config, state, alarm_boundary as _boundary
from .event_logging import start_record_event, stop_record_event
@@ -100,2 +100,5 @@
"""
+ if _boundary.enabled():
+ contexts = _boundary.capture_contexts(config.CAMERA_CONFIG)
+ payload = {**_boundary.filter_ws({**payload, "_cc10_contexts": contexts}), "_cc10_contexts": contexts}
if state.alarm_queue is not None and state.MAIN_LOOP is not None:
@@ -132,2 +135,3 @@
try:
+ guarded_payload = _boundary.filter_ws(payload)
# Строго минимальный словарь только с нужными ключами
@@ -135,4 +139,4 @@
minimal = {
- "type": payload.get("type"),
- "data": bool(payload.get("data")),
+ "type": guarded_payload.get("type"),
+ "data": bool(guarded_payload.get("data")),
}
@@ -140,3 +144,3 @@
# на случай если кто-то положил уже готовую строку/другую структуру
- minimal = payload
+ minimal = guarded_payload
@@ -169,3 +173,3 @@
"""
- _dispatch_alarm({"type": "freq_alarm", "data": bool(state_on)})
+ _dispatch_alarm({"type": "freq_alarm", "data": bool(state_on) and _boundary.arm_allowed(cam_idx)})
--- a/ptz_tracker_modular/main.py
+++ b/ptz_tracker_modular/main.py
@@ -217,2 +217,8 @@
async def main() -> None:
+ from ptz_tracker_modular import inspection_handoff
+ if inspection_handoff.enabled():
+ from ptz_tracker_modular.inspection_startup import configure_runtime
+ inspection = configure_runtime()
+ else:
+ inspection = None
# --- Инициализация общего состояния ---
@@ -479,3 +485,3 @@
# ---- Опциональный smoke-тест тревоги (по первому MAC) ----
- if os.getenv("ALARM_SMOKE", "0") in ("1", "true", "TRUE", "yes", "YES"):
+ if getattr(config, "UNKNOWN_INSPECTION_ENABLE", False) is not True and os.getenv("ALARM_SMOKE", "0") in ("1", "true", "TRUE", "yes", "YES"):
async def _smoke():
@@ -528,2 +534,5 @@
+ if inspection is not None:
+ tasks.append(watch(inspection.recognition_loop(), "unknown_recognition"))
+
try:
--- a/ptz_tracker_modular/postprocess.py
+++ b/ptz_tracker_modular/postprocess.py
@@ -11,2 +11,3 @@
from . import config, state, visual_control
+from . import unknown_inspection as inspection
from . import motion_detector
@@ -47,2 +48,3 @@
logger = logging.getLogger("PTZTracker")
+_inspection_move_emit = move_ptz_bounded
@@ -52,3 +54,4 @@
"""Keep class filtering on the detector result's actual device."""
- return torch.as_tensor(config.TARGET_CLASSES, device=classes.device, dtype=classes.dtype)
+ return torch.as_tensor((0,) if _inspection_enabled() else config.TARGET_CLASSES,
+ device=classes.device, dtype=classes.dtype)
@@ -57,2 +60,4 @@
"""Return the detector class name retained by candidate/visual tracking."""
+ if getattr(config, "UNKNOWN_INSPECTION_ENABLE", False) is True:
+ return "unknown airborne object"
try:
@@ -540,3 +545,10 @@
st["ptz_move_seq"] = int(st.get("ptz_move_seq", 0) or 0) + 1
+ inspection_on = getattr(config, "UNKNOWN_INSPECTION_ENABLE", False) is True
+ old_owner = visual_control.owner(st) if inspection_on else None
st["zoom_rearm_epoch"] = int(st.get("zoom_rearm_epoch", 0) or 0) + 1
+ session = st.get("inspection_session")
+ if inspection_on and isinstance(session, inspection.Session) and session.owner == old_owner:
+ session.owner = visual_control.owner(st)
+ session.recent.clear()
+ session.revoke_semantics("zoom_revalidation")
st["zoom_rearm_required"] = True
@@ -650,2 +662,9 @@
"""Require strong detector evidence after any optical narrowing."""
+ if _inspection_enabled():
+ cfg = getattr(config, "UNKNOWN_INSPECTION_SETTINGS", None)
+ session = st.get("inspection_session")
+ return bool(isinstance(cfg, inspection.Settings) and isinstance(session, inspection.Session)
+ and session.live(time.monotonic()) and inspection.finite(confidence)
+ and confidence >= cfg.proposal_min
+ and 0 <= time.time()-session.last_at <= .65)
followup = bool(
@@ -3972,2 +3991,3 @@
frame_h: int,
+ *, inspection_state: dict | None = None,
) -> tuple[bool, float]:
@@ -3990,2 +4010,8 @@
detector_conf = float(matched[1]) if matched is not None else 0.0
+ if _inspection_enabled():
+ st = inspection_state or {}
+ session = st.get("inspection_session")
+ allowed = st.get("inspection_authorized") is True and isinstance(session, inspection.Session) and matched is not None and session.contract == getattr(config, "UNKNOWN_INSPECTION_SETTINGS", None) and session.alarm_allowed(
+ time.time(), time.monotonic(), visual_control.owner(st), tuple(target_bbox), (frame_h, frame_w))
+ return bool(allowed), session.semantic_score if allowed else 0.
threshold = float(getattr(config, "ALARM_CONF", 0.50))
@@ -4016,2 +4042,9 @@
"""Keep localization, class identity and protection as separate states."""
+ if _inspection_enabled():
+ session = st.get("inspection_session")
+ st["tracking_state"] = "inspecting"
+ st["identity_state"] = session.decision if isinstance(session, inspection.Session) else "unresolved"
+ st["identity_class"] = -1
+ st["protection_state"] = "pending" if alarm_eligible else "safe"
+ return
source = str(target_source or "none")
@@ -4093,2 +4126,7 @@
def _format_visual_tracking_label(st: dict, *, tracker_score: float) -> str:
+ if _inspection_enabled():
+ session = st.get("inspection_session")
+ if isinstance(session, inspection.Session):
+ return f"{session.decision}: {session.semantic_name or 'unknown object'}; inspecting"
+ return "unknown object; inspection unavailable"
identity_state = str(st.get("identity_state", "unknown"))
@@ -4569,2 +4607,4 @@
"""Break continuous zoom-in into short feedback-controlled steps."""
+ if _inspection_enabled():
+ zoom_cmd = min(float(zoom_cmd), .10)
pulse_until = float(st.get("zoom_step_until", 0.0) or 0.0)
@@ -5454,3 +5494,3 @@
-def _enter_acquire_locked(cam_idx: int, now: float) -> bool:
+def _legacy_enter_acquire_locked(cam_idx: int, now: float) -> bool:
st = state.ensure_cam_state(cam_idx, is_ptz=True)
@@ -5978,3 +6018,3 @@
-def _enter_track_locked(cam_idx: int) -> None:
+def _legacy_enter_track_locked(cam_idx: int) -> None:
st = state.ensure_cam_state(cam_idx, is_ptz=cam_idx in config.PTZ_CAM_IDS)
@@ -6541,3 +6581,3 @@
alarm_eligible, alarm_conf = _alarm_eligible_for_target(
- bbox, target_class, detector_targets, width, height)
+ bbox, target_class, detector_targets, width, height, inspection_state=st)
identity_conf = float(matched[1]) if matched is not None and int(matched[2]) == target_class else 0.
@@ -6548,3 +6588,3 @@
alarm_eligible=alarm_eligible, cam_idx=cam_idx)
- alarms.ingest_detection(cam_idx, alarm_eligible)
+ alarms.ingest_detection(cam_idx, bool(alarm_eligible) and (not _inspection_enabled() or _inspection_alarm_ready(st)))
@@ -6596,2 +6636,4 @@
if not visual_only:
+ if _inspection_enabled():
+ eligible = bool(eligible) and _inspection_alarm_ready(st)
alarms.ingest_detection(cam_idx, eligible)
@@ -6805,2 +6847,8 @@
+ if _inspection_enabled() and not _inspection_before_frame(
+ cam_idx, st, res, frame_bgr, source_seq, is_ptz, visual_only, visual_sample):
+ return
+ if _inspection_enabled():
+ boxes_t = getattr(res, "boxes", None)
+
_cfg = config.CAMERA_CONFIG.get(int(cam_idx), {}) if hasattr(config, "CAMERA_CONFIG") else {}
@@ -6874,3 +6922,3 @@
mask = torch.isin(clss, _targets_tensor_like(clss))
- if getattr(config, "DRONE_ONLY", False):
+ if not _inspection_enabled() and getattr(config, "DRONE_ONLY", False):
drone_id = int(getattr(config, "DRONE_CLASS_ID", 1))
@@ -6887,3 +6935,3 @@
conf_by_cls = getattr(config, "DETECT_CONF_BY_CLASS", None)
- if isinstance(conf_by_cls, dict) and conf_by_cls:
+ if not _inspection_enabled() and isinstance(conf_by_cls, dict) and conf_by_cls:
for k, v in conf_by_cls.items():
@@ -6896,2 +6944,5 @@
+ if _inspection_enabled():
+ conf_thr = torch.full_like(confs, config.UNKNOWN_INSPECTION_SETTINGS.proposal_min)
+
# === Motion-aided detection: boost conf для боксов внутри motion ROI ===
@@ -6902,2 +6953,3 @@
is_ptz
+ and not _inspection_enabled()
and bool(getattr(config, "MOTION_DETECT_ENABLE", False))
@@ -6924,3 +6976,3 @@
# optional drone size filter (fractions of frame)
- if getattr(config, "DRONE_SIZE_FILTER", False):
+ if not _inspection_enabled() and getattr(config, "DRONE_SIZE_FILTER", False):
drone_ids_cfg = getattr(config, "DRONE_CLASS_ID", 1)
@@ -7943,3 +7995,3 @@
(int(x1), int(y1), int(x2), int(y2)),
- int(best_cls), detector_targets, w, h,
+ int(best_cls), detector_targets, w, h, inspection_state=st,
)
@@ -10272 +10324,231 @@
return response
+
+
+def _enter_acquire_locked(cam_idx: int, now: float):
+ st = state.ensure_cam_state(cam_idx, is_ptz=True)
+ old_owner = visual_control.owner(st)
+ count = int(st.get("zoom_no_effect_count", 0) or 0)
+ blocked = bool(st.get("zoom_no_effect_blocked", False))
+ result = _legacy_enter_acquire_locked(cam_idx, now)
+ if _inspection_enabled():
+ st["zoom_no_effect_count"] = max(count, int(st.get("zoom_no_effect_count", 0) or 0))
+ st["zoom_no_effect_blocked"] = blocked or bool(st.get("zoom_no_effect_blocked", False))
+ session = st.get("inspection_session")
+ if isinstance(session, inspection.Session) and session.owner == old_owner:
+ new_owner = visual_control.owner(st)
+ if new_owner != old_owner:
+ session.owner = new_owner
+ session.recent.clear()
+ session.revoke_semantics("known_owner_transition")
+ return result
+
+
+def _enter_track_locked(cam_idx: int):
+ st = state.ensure_cam_state(cam_idx, is_ptz=True)
+ old_owner = visual_control.owner(st)
+ count = int(st.get("zoom_no_effect_count", 0) or 0)
+ blocked = bool(st.get("zoom_no_effect_blocked", False))
+ result = _legacy_enter_track_locked(cam_idx)
+ if _inspection_enabled():
+ st["zoom_no_effect_count"] = max(count, int(st.get("zoom_no_effect_count", 0) or 0))
+ st["zoom_no_effect_blocked"] = blocked or bool(st.get("zoom_no_effect_blocked", False))
+ session = st.get("inspection_session")
+ if isinstance(session, inspection.Session) and session.owner == old_owner:
+ new_owner = visual_control.owner(st)
+ if new_owner != old_owner:
+ session.owner = new_owner
+ session.recent.clear()
+ session.revoke_semantics("known_owner_transition")
+ return result
+
+
+def _inspection_enabled():
+ return getattr(config, 'UNKNOWN_INSPECTION_ENABLE', False) is True
+
+
+def _inspection_alarm_ready(st):
+ from .inspection_runtime import current_detector
+ session = st.get('inspection_session')
+ cfg = getattr(config, 'UNKNOWN_INSPECTION_SETTINGS', None)
+ return bool(isinstance(cfg, inspection.Settings) and cfg.enabled
+ and isinstance(session, inspection.Session) and session.contract == cfg
+ and st.get('inspection_authorized') is True
+ and st.get('mode') not in {'manual', 'MANUAL', 'RETURNING', 'RETURN', 'GOTO'}
+ and current_detector(st, time.monotonic())
+ and _inspection_common_ready(st)
+ and session.alarm_allowed(time.time(), time.monotonic(), visual_control.owner(st),
+ tuple(st.get('last_bbox') or session.bbox or ()), session.shape))
+
+
+def _inspection_common_ready(st):
+ """Independent monotonic two-frame veto; no binding is no alarm."""
+ guard = st.get('inspection_common_alarm_guard')
+ try:
+ return callable(guard) and guard() is True
+ except Exception:
+ return False
+
+
+def _inspection_before_frame(cam, st, result, frame, seq, is_ptz, visual_only, sample):
+ """No inference here: only bounded metadata and current-frame admission."""
+ cfg = getattr(config, 'UNKNOWN_INSPECTION_SETTINGS', None)
+ session = st.get('inspection_session')
+ now, mono = time.time(), time.monotonic()
+
+ def deny(reason):
+ if isinstance(session, inspection.Session) and session.owner != visual_control.owner(st):
+ return False # an old callback cannot STOP or clear a newer owner
+ st['alarm_gate_eligible'] = False
+ st['alarm_detector_conf'] = 0.
+ st['inspection_reason'] = reason
+ if isinstance(session, inspection.Session):
+ session.revoke_semantics(reason)
+ if st.get('inspection_stop_reason') != reason:
+ stop_ptz(cam, source='stop', generation=int(st.get('ptz_generation', 0) or 0))
+ st['inspection_stop_reason'] = reason
+ if not visual_only:
+ alarms.ingest_detection(cam, False)
+ return False
+
+ if not is_ptz:
+ return deny('inspection_ptz_only')
+ if not isinstance(cfg, inspection.Settings) or not cfg.enabled:
+ return deny('missing_validated_contract')
+ if isinstance(session, inspection.Session) and session.contract is not None and session.contract != cfg:
+ session.phase = 'closed'
+ return deny('model_contract_changed')
+ if st.get('inspection_authorized') is not True:
+ return deny('inspection_not_authorized')
+ if st.get('mode') in {'manual', 'MANUAL', 'RETURNING', 'RETURN', 'GOTO'}:
+ return deny('camera_not_authorized_for_inspection')
+ incoming = getattr(result, 'inspection_observation', None)
+ if isinstance(incoming, inspection.Observation) and incoming.owner != visual_control.owner(st):
+ return False
+ from .inspection_runtime import provenance, check_stamp
+ reason = provenance(st, result, sample, camera=cam, seq=seq,
+ owner=visual_control.owner(st), mono=mono, visual_only=visual_only)
+ if reason:
+ return deny(reason)
+ if isinstance(session, inspection.Session) and session.phase == 'closed':
+ # A new SEARCH owner may inspect another object. A closed callback itself
+ # never renews its session/budget. Same-object retry is deliberately not
+ # automatic in this first candidate; the discovery scheduler must retire
+ # its bounded suppression entry explicitly.
+ another = (isinstance(incoming, inspection.Observation)
+ and any(inspection.valid_box(b, incoming.shape)
+ and not inspection.same_object(session.bbox, b, incoming.shape)
+ for b, _, _ in incoming.detections))
+ if (another and not st.get('tracking_active')
+ and st.get('mode') in {'IDLE', 'SWEEP', 'auto'}):
+ session = None
+ st.pop('inspection_session', None)
+ else:
+ return deny('inspection_closed')
+ if isinstance(session, inspection.Session):
+ if session.decision == 'target' and not 0 <= now-session.semantic_at <= .65:
+ session.revoke_semantics('semantic_evidence_expired')
+ if session.owner != visual_control.owner(st):
+ session.phase = 'closed'
+ return deny('owner_changed')
+ if not session.live(mono):
+ session.phase = 'closed'
+ return deny('inspection_timeout')
+ if session.decision == 'non_target':
+ session.phase = 'closed'
+ deny('confirmed_non_target')
+ _end_track_and_park(cam, reason='inspection confirmed non-target')
+ return False
+ if session.phase == 'closed':
+ return deny('inspection_closed')
+ if visual_only:
+ if not isinstance(session, inspection.Session) or session.phase != 'inspection':
+ return deny('no_inspection_owner')
+ if (sample is None or not sample.result.ok or sample.result.bbox is None
+ or not 0 <= now-session.last_at <= .65
+ or tuple(frame.shape[:2]) != session.shape
+ or not inspection.same_object(session.bbox, sample.result.bbox, session.shape)):
+ return deny('unverified_visual_continuity')
+ st['inspection_control_deadline'] = min(
+ mono + max(0., .25-(now-sample.captured_at)), st['inspection_input_mono']+.25)
+ return True
+ observation = getattr(result, 'inspection_observation', None)
+ if not isinstance(observation, inspection.Observation) or observation.source_seq != seq:
+ return deny('missing_original_frame_metadata')
+ if observation.shape != tuple(frame.shape[:2]) or observation.owner != visual_control.owner(st):
+ return deny('foreign_observation')
+ if session is None:
+ st['inspection_serial'] = int(st.get('inspection_serial', 0) or 0)+1
+ session = inspection.Session(cam, st['inspection_serial'], visual_control.owner(st),
+ mono, mono+cfg.budget_sec)
+ st['inspection_session'] = session
+ st['purpose'] = 'inspection'
+ admitted = session.observe(observation, cfg, now, mono)
+ recognition = getattr(result, 'inspection_recognition', None)
+ if admitted and isinstance(recognition, inspection.Recognition):
+ rec_stamp = getattr(result, 'inspection_recognition_stamp', None)
+ if check_stamp(rec_stamp, camera=cam, seq=recognition.source_seq,
+ owner=recognition.owner, expected_owner=visual_control.owner(st),
+ binding=st.get('inspection_source_binding'), now=mono, age=.65):
+ session.recognize(recognition, cfg, now, mono)
+ if session.semantic_seq == recognition.source_seq and session.semantic_votes:
+ st['inspection_semantic_stamp'] = rec_stamp
+ else:
+ session.revoke_semantics('stale_or_foreign_recognition_stamp')
+ if not admitted:
+ return deny(session.reason)
+ if session.decision == 'non_target':
+ session.phase = 'closed'
+ deny('confirmed_non_target')
+ _end_track_and_park(cam, reason='inspection confirmed non-target')
+ return False
+ # Old-frame evidence may validate identity, but must not replay a MOVE.
+ if sample is None and (not 0 <= now-observation.observed_at <= .25
+ or not 0 <= mono-st['inspection_input_mono'] <= .25):
+ return deny('too_old_for_motion')
+ st['inspection_stop_reason'] = ''
+ st['inspection_reason'] = session.reason
+ st['purpose'] = 'target' if session.decision == 'target' else 'inspection'
+ st['inspection_control_deadline'] = min(
+ mono + max(0., .25-(now-observation.observed_at)), st['inspection_input_mono']+.25)
+ # The legacy ranker must never select a stronger neighboring proposal over
+ # the object whose temporal admission we just checked.
+ if getattr(result, 'boxes', None) is not None:
+ raw_boxes = result.boxes.xyxy.detach().cpu().tolist()
+ indices = [i for i, b in enumerate(raw_boxes) if tuple(b) == session.bbox]
+ if not indices:
+ return deny('proposal_result_mismatch')
+ result.boxes = result.boxes[indices[:1]]
+ return True
+
+
+def move_ptz_bounded(cam_idx, pan_speed, tilt_speed, zoom=0., **kwargs):
+ """Last-boundary recheck; the existing physical worker is still authoritative."""
+ if _inspection_enabled():
+ from .inspection_runtime import current_detector
+ st = state.ptz_states.get(cam_idx, {})
+ session = st.get('inspection_session')
+ now, mono = time.time(), time.monotonic()
+ if isinstance(session, inspection.Session) and session.decision == 'target':
+ stamp = st.get('inspection_semantic_stamp')
+ from .inspection_runtime import check_stamp
+ if (not 0 <= now-session.semantic_at <= .65
+ or not check_stamp(stamp, camera=cam_idx, seq=session.semantic_seq,
+ owner=session.owner, expected_owner=visual_control.owner(st),
+ binding=st.get('inspection_source_binding'), now=mono, age=.65)):
+ session.revoke_semantics('semantic_evidence_expired_at_emit')
+ elif mono >= session.deadline_mono and not _inspection_common_ready(st):
+ session.revoke_semantics('independent_semantic_evidence_expired_at_emit')
+ valid = (isinstance(session, inspection.Session)
+ and st.get('inspection_authorized') is True
+ and st.get('mode') not in {'manual', 'MANUAL', 'RETURNING', 'RETURN', 'GOTO'}
+ and session.live(mono) and session.phase == 'inspection'
+ and session.decision != 'non_target'
+ and session.owner == visual_control.owner(st)
+ and current_detector(st, mono)
+ and 0 <= now-session.last_at <= .65
+ and mono < float(st.get('inspection_control_deadline', 0.) or 0.))
+ if not valid:
+ stop_ptz(cam_idx, source='stop', generation=int(st.get('ptz_generation', 0) or 0))
+ return
+ zoom = min(float(zoom), .10)
+ return _inspection_move_emit(cam_idx, pan_speed, tilt_speed, zoom, **kwargs)
--- a/ptz_tracker_modular/streaming.py
+++ b/ptz_tracker_modular/streaming.py
@@ -25,2 +25,4 @@
from .postprocess import postprocess_control
+from . import inspection_handoff
+from uuid import uuid4
from .visual_tracker import visual_tracker_manager
@@ -60,3 +62,3 @@
_cpp_stream_map_missing_logged: str = ""
-_visual_feed_pending: Dict[int, Tuple[np.ndarray, int, float]] = {}
+_visual_feed_pending: Dict[int, Tuple[np.ndarray, int, float, Any]] = {}
_visual_feed_last_served: Dict[int, float] = {}
@@ -228,3 +230,3 @@
waiting = []
- for cam_id, (_, _, queued_at) in _visual_feed_pending.items():
+ for cam_id, (_, _, queued_at, _) in _visual_feed_pending.items():
st = state.ptz_states.get(int(cam_id), {})
@@ -256,3 +258,3 @@
break
- frame_bgr, source_seq, queued_at = _visual_feed_pending.pop(cam_id)
+ frame_bgr, source_seq, queued_at, ticket = _visual_feed_pending.pop(cam_id)
captured_at = _visual_feed_captured_at.pop(cam_id, time.time())
@@ -274,2 +276,3 @@
captured_at=captured_at,
+ inspection_ticket=ticket,
),
@@ -299,2 +302,3 @@
source_seq: int,
+ *, inspection_ticket=None,
) -> None:
@@ -315,4 +319,6 @@
queued_at = float(previous[2]) if previous is not None else time.perf_counter()
- _visual_feed_pending[int(cam_id)] = (frame_bgr, int(source_seq), queued_at)
- _visual_feed_captured_at[int(cam_id)] = time.time()
+ _visual_feed_pending[int(cam_id)] = (frame_bgr, int(source_seq), queued_at, inspection_ticket)
+ _visual_feed_captured_at[int(cam_id)] = (
+ inspection_ticket.stamp.decode_utc_ns/1e9 if inspection_ticket else time.time()
+ )
if _visual_feed_worker_task is None or _visual_feed_worker_task.done():
@@ -776,2 +782,4 @@
st = state.ptz_states.get(cam_id, {})
+ if getattr(config, "UNKNOWN_INSPECTION_ENABLE", False) is True:
+ continue # UNKNOWN publishes from semantic eligibility, never recording.
has_target_now = bool(st.get("rec_active", False))
@@ -1910,2 +1918,4 @@
"""Replace a queued stale frame with the newest frame from the same camera."""
+ if inspection_handoff.enabled():
+ return inspection_handoff.require_configured().refresh(item)
cam_idx, frame_bgr, is_ptz, source_seq, fut, queued_at = item
@@ -1967,2 +1977,3 @@
source_seq: int = 0,
+ *, inspection_ticket=None,
) -> None:
@@ -1971,5 +1982,7 @@
async with self._cond:
- self._buf.append(
- (cam_idx, frame_bgr, is_ptz, int(source_seq), fut, time.perf_counter())
- )
+ item = cam_idx, frame_bgr, is_ptz, int(source_seq), fut, time.perf_counter()
+ if inspection_handoff.enabled():
+ if not inspection_handoff.require_configured().bind_item(item, inspection_ticket):
+ return
+ self._buf.append(item)
self._cond.notify()
@@ -2034,2 +2047,6 @@
])
+ if inspection_handoff.enabled():
+ batch = inspection_handoff.require_configured().prune(batch)
+ if not batch:
+ continue
frames = [b[1] for b in batch]
@@ -2037,3 +2054,6 @@
infer_t0 = time.perf_counter()
- results = await loop.run_in_executor(None, run, frames)
+ detect = run
+ if inspection_handoff.enabled():
+ detect = inspection_handoff.require_configured().detect
+ results = await loop.run_in_executor(None, detect, frames)
forward_ms = (time.perf_counter() - infer_t0) * 1000.0
@@ -2044,3 +2064,3 @@
)
- if bool(getattr(config, "SAHI_ENABLE", False)):
+ if bool(getattr(config, "SAHI_ENABLE", False)) and not inspection_handoff.enabled():
results = await loop.run_in_executor(
@@ -2108,3 +2128,6 @@
+ handoff = inspection_handoff.require_configured() if inspection_handoff.enabled() else None
while True:
+ source_cameras = set()
+ stream_epoch = uuid4().hex if handoff else None
try:
@@ -2196,2 +2219,10 @@
+ inspection_ptz = handoff is not None and idx in handoff.bridge.crops.cameras
+ epoch = handoff.camera_epoch(idx) if inspection_ptz else None
+ if inspection_ptz:
+ if not handoff.begin_source(idx, f"cpp_{idx_raw}", stream_epoch, epoch):
+ continue
+ source_cameras.add(idx)
+
+ ticket = None
now_pc = time.perf_counter()
@@ -2212,2 +2243,4 @@
if img is not None:
+ if inspection_ptz:
+ ticket = handoff.accepted(idx, img, source_seq, epoch)
_publish_frontend_raw_preview(idx, img, pst, source_seq, priority=4)
@@ -2223,8 +2256,15 @@
- if getattr(config, "DROP_DECODE_WHEN_BUSY", False) and pst["proc_busy"]:
+ if getattr(config, "DROP_DECODE_WHEN_BUSY", False) and pst["proc_busy"] and (
+ handoff is None or inspection_ptz
+ ):
img_busy = img if img is not None else _decode_image(encoded)
if img_busy is not None:
- _feed_visual_tracker_frame(idx, img_busy, pst, source_seq)
- pst["pending_frame"] = img_busy
- pst["pending_source_seq"] = int(source_seq)
+ if handoff is None:
+ pst["pending_frame"] = img_busy
+ pst["pending_source_seq"] = int(source_seq)
+ elif inspection_ptz:
+ if img is None:
+ ticket = handoff.accepted(idx, img_busy, source_seq, epoch)
+ handoff.pending(ticket)
+ _feed_visual_tracker_frame(idx, img_busy, pst, source_seq, inspection_ticket=ticket)
if can_publish and _frontend_raw_preview_due(idx, pst):
@@ -2236,2 +2276,4 @@
img = _decode_image(encoded)
+ if img is not None and inspection_ptz:
+ ticket = handoff.accepted(idx, img, source_seq, epoch)
if img is None:
@@ -2242,3 +2284,3 @@
- if skip_infer_for_non_ptz:
+ if skip_infer_for_non_ptz or (handoff is not None and not inspection_ptz):
# Still keep the UI alive for non-PTZ/panorama streams. Detection
@@ -2250,2 +2292,4 @@
+ if inspection_ptz and ticket is None:
+ continue
now = time.time()
@@ -2284,3 +2328,3 @@
if pst["proc_busy"]:
- _feed_visual_tracker_frame(idx, img, pst, source_seq)
+ _feed_visual_tracker_frame(idx, img, pst, source_seq, inspection_ticket=ticket)
skipped_busy_total += 1
@@ -2294,3 +2338,3 @@
if (now_pc - last_submit) < infer_min_dt:
- _feed_visual_tracker_frame(idx, img, pst, source_seq)
+ _feed_visual_tracker_frame(idx, img, pst, source_seq, inspection_ticket=ticket)
if publish_raw_allowed:
@@ -2306,3 +2350,3 @@
- async def process_frame(cam_idx: int, frame, frame_seq: int) -> None:
+ async def process_frame(cam_idx: int, frame, frame_seq: int, frame_ticket=None) -> None:
try:
@@ -2313,2 +2357,3 @@
source_seq=frame_seq,
+ inspection_ticket=frame_ticket,
)
@@ -2318,2 +2363,3 @@
pst_done = state.ptz_states[cam_idx]
+ next_ticket = pst_done.pop("pending_inspection_ticket", None)
next_frame = pst_done.pop("pending_frame", None)
@@ -2331,3 +2377,3 @@
pst_done["proc_busy"] = True
- asyncio.create_task(process_frame(cam_idx, next_frame, next_seq))
+ asyncio.create_task(process_frame(cam_idx, next_frame, next_seq, next_ticket))
else:
@@ -2341,3 +2387,3 @@
- asyncio.create_task(process_frame(idx, img, source_seq))
+ asyncio.create_task(process_frame(idx, img, source_seq, ticket))
@@ -2345,3 +2391,7 @@
logger.error("[CPP WS] error: %s", exc)
- await asyncio.sleep(0.5)
+ finally:
+ if handoff is not None:
+ for camera in source_cameras:
+ handoff.end_source(camera, stream_epoch)
+ await asyncio.sleep(0.5)
@@ -2475,2 +2525,8 @@
with ExitStack() as locks:
+ if inspection_handoff.enabled():
+ handoff = inspection_handoff.require_configured()
+ for cid in sorted(ids):
+ locks.enter_context(visual_control.control_lock(cid))
+ for cid in ids:
+ handoff.end_source(cid, reason='camera_address_changed')
for cid in ids:
@@ -2565,3 +2621,3 @@
def _update_visual_feed(cam_id: int, frame_bgr: np.ndarray, source_seq: int,
- captured_at: Optional[float] = None) -> None:
+ captured_at: Optional[float] = None, *, inspection_ticket=None) -> None:
with visual_control.control_lock(cam_id):
@@ -2572,2 +2628,10 @@
token = visual_control.owner(st)
+ handoff = inspection_handoff.require_configured() if inspection_handoff.enabled() else None
+ if handoff is not None and (
+ not handoff.current(inspection_ticket, age=.25)
+ or inspection_ticket.pixels is not frame_bgr
+ or inspection_ticket.stamp.camera_id != cam_id
+ or inspection_ticket.stamp.source_seq != source_seq
+ ):
+ return
result = visual_control_probe.call_tracker_update(visual_tracker_manager.update, cam_id, frame_bgr, source_seq=source_seq)
@@ -2582,3 +2646,8 @@
return
- sample = visual_control.VisualSample(token, int(source_seq), captured_at, result)
+ if handoff is not None:
+ sample = handoff.visual_sample(inspection_ticket, result)
+ if sample is None:
+ return
+ else:
+ sample = visual_control.VisualSample(token, int(source_seq), captured_at, result)
postprocess_control(cam_id, frame_bgr, None, True, source_seq,
@@ -2592,2 +2661,4 @@
"""Pair YOLO with an exact visual observation, independently of GPU latency."""
+ if inspection_handoff.enabled():
+ return inspection_handoff.require_configured().prepare(item)
cam_id, frame, is_ptz, source_seq, future, queued_at = item
@@ -2609,2 +2680,4 @@
def _postprocess_inference_item(cam_id, frame, res, is_ptz, source_seq, future):
+ if inspection_handoff.enabled():
+ return inspection_handoff.require_configured().process_item(cam_id, frame, res, is_ptz, source_seq, future)
sample = getattr(future, 'visual_sample', None)
--- a/ptz_tracker_modular/visual_control_probe.py
+++ b/ptz_tracker_modular/visual_control_probe.py
@@ -87,4 +87,4 @@
@wraps(function)
- def wrapped(camera, frame, st, source_seq):
- result = function(camera, frame, st, source_seq)
+ def wrapped(camera, frame, st, source_seq, **kwargs):
+ result = function(camera, frame, st, source_seq, **kwargs)
try:
@@ -103,3 +103,3 @@
@wraps(function)
- def wrapped(camera, frame, source_seq, captured_at=None):
+ def wrapped(camera, frame, source_seq, captured_at=None, **kwargs):
start = _perf()
@@ -117,3 +117,3 @@
try:
- return function(camera, frame, source_seq, captured_at=captured_at)
+ return function(camera, frame, source_seq, captured_at=captured_at, **kwargs)
finally:

@ -1,272 +0,0 @@
"""Offline checks: real candidate alarm functions, fake transports; no model imports."""
import ast, asyncio, dataclasses as dc, importlib, json, logging, math
from pathlib import Path
import sys, types, unittest
from unittest.mock import patch
ROOT = Path(__file__).resolve().parent
PKG = 'cc10_offline'
pkg = types.ModuleType(PKG); pkg.__path__ = [str(ROOT/'ptz_tracker_modular')]; sys.modules[PKG]=pkg
cfg = types.ModuleType(PKG+'.config')
cfg.UNKNOWN_INSPECTION_ENABLE=True
cfg.CAMERA_CONFIG={10: {'mac':'00:11:22:33:44:55'},8: {'mac':'00:11:22:33:44:66'}}
cfg.ALARM_COUNT_ON=1;cfg.ALARM_COUNT_OFF=3;cfg.ALARM_HTTP_ENABLE=True
cfg.ALARM_HTTP_BASE='https://offline.invalid';cfg.ALARM_HTTP_PATH='/videodata'
sys.modules[PKG+'.config']=cfg
state=types.ModuleType(PKG+'.state');state.MAIN_LOOP=None;state.alarm_queue=None;state.detected_cameras={10,8}
sys.modules[PKG+'.state']=state
cams=types.ModuleType(PKG+'.cameras_io');cams.get_all=lambda:cfg.CAMERA_CONFIG
sys.modules[PKG+'.cameras_io']=cams
policy=importlib.import_module(PKG+'.alarm_eligibility')
contracts=importlib.import_module(PKG+'.model_class_contract')
boundary=importlib.import_module(PKG+'.alarm_boundary')
alarms=importlib.import_module(PKG+'.alarms')
Context,Frame,Semantic,AlarmEligibility=policy.Context,policy.Frame,policy.Semantic,policy.AlarmEligibility
A='a'*64;B='b'*64
NAMES=('multirotor_uav','fixed_wing_uav','bird','manned_aircraft')
def model(role='semantic_classifier', **kw):
data=dict(path='fake.pt',actual_sha=B if role=='semantic_classifier' else A,
expected_sha=B if role=='semantic_classifier' else A,
raw_names=NAMES if role=='semantic_classifier' else ['airborne_object'],
role=role,metadata_source='loaded_model.names',actual_task='classify' if role=='semantic_classifier' else 'detect')
data.update(kw)
return contracts.validate_contract(**data)
def scores(name='multirotor_uav'):
return tuple((n,.91 if n==name else .03) for n in NAMES)
class Base(unittest.TestCase):
def setUp(self):
cfg.UNKNOWN_INSPECTION_ENABLE=True;cfg.CAMERA_CONFIG={10:{'mac':'00:11:22:33:44:55'},8:{'mac':'00:11:22:33:44:66'}}
self.clock=10.2
self.ctx=Context(10,1,('auto',7,12),'camera21:stream_epoch=1',A,B)
self.gate=AlarmEligibility()
self.gate.begin(self.ctx,proposal_contract=model('generic_detector'),classifier_contract=model())
self.provider={10:self.ctx}
boundary.bind_guard(self.gate,lambda c:self.provider.get(c))
self.tm=patch.object(boundary,'time',types.SimpleNamespace(monotonic=lambda:self.clock));self.tm.start();self.addCleanup(self.tm.stop)
alarms._H.clear();alarms._http_queue=asyncio.Queue();state.alarm_queue=asyncio.Queue();state.MAIN_LOOP=None
self.f1=Frame(1,10.,(100,100,200,200),(720,1280))
self.f2=Frame(2,10.1,(101,100,201,200),(720,1280))
def put(self,frame,name='multirotor_uav',**kw):
self.assertTrue(self.gate.observe(self.ctx,frame,self.clock))
return self.gate.submit(self.ctx,Semantic(frame,B,scores(name),100,**kw),self.clock)
def confirm(self):
self.assertFalse(self.put(self.f1));self.assertTrue(self.put(self.f2))
class EligibilityTests(Base):
def test_unknown_record_and_tracker_score_are_not_evidence(self):
state.rec_active=True;state.tracker_score=.999
self.assertFalse(self.gate.eligible(self.ctx,self.clock))
self.assertFalse(boundary.arm_allowed(10))
def test_one_frame_denied_two_frames_allowed(self): self.confirm()
def test_duplicate_cached_frame_never_second_vote(self):
self.put(self.f1)
self.assertFalse(self.gate.submit(self.ctx,Semantic(self.f1,B,scores(),100),self.clock))
def test_reordered_frame_cannot_vote(self):
self.put(self.f2)
self.assertFalse(self.gate.observe(self.ctx,self.f1,self.clock))
self.assertFalse(self.gate.eligible(self.ctx,self.clock))
def test_result_must_match_original_frame_exactly(self):
self.gate.observe(self.ctx,self.f1,self.clock)
forged=dc.replace(self.f1,bbox=(100,100,201,200))
self.assertFalse(self.gate.submit(self.ctx,Semantic(forged,B,scores(),100),self.clock))
def test_inference_completion_cannot_replace_acquisition(self):
self.gate.observe(self.ctx,self.f1,self.clock)
forged=dc.replace(self.f1,acquired_mono=self.clock)
self.assertFalse(self.gate.submit(self.ctx,Semantic(forged,B,scores(),100),self.clock))
def test_wrong_context_dimensions(self):
self.confirm()
for field,value in [('camera',8),('inspection_id',2),('owner',('auto',8,12)),('source_id','camera21:stream_epoch=2'),('classifier_sha','c'*64),('proposal_sha','d'*64)]:
with self.subTest(field=field):self.assertFalse(self.gate.eligible(dc.replace(self.ctx,**{field:value}),self.clock))
def test_unpinned_classifier_does_not_vote(self):
self.put(self.f1);self.gate.observe(self.ctx,self.f2,self.clock)
self.assertFalse(self.gate.submit(self.ctx,Semantic(self.f2,'c'*64,scores(),100),self.clock))
def test_both_semantic_frames_must_remain_fresh(self):
self.confirm();self.assertFalse(self.gate.eligible(self.ctx,10.66))
def test_future_and_nan_time_rejected(self):
for value in (11.,float('nan'),float('inf')):
with self.subTest(value=value):self.assertFalse(self.gate.observe(self.ctx,dc.replace(self.f1,acquired_mono=value),self.clock))
def test_duplicate_timestamp_not_independent(self):
self.put(self.f1);self.assertFalse(self.gate.observe(self.ctx,dc.replace(self.f2,acquired_mono=10.),self.clock))
def test_semantic_class_must_be_consistent(self):
self.put(self.f1);self.assertFalse(self.put(self.f2,'fixed_wing_uav'))
def test_bird_or_manned_aircraft_never_alarm(self):
for name in ('bird','manned_aircraft'):
with self.subTest(name=name):
self.setUp();self.assertFalse(self.put(self.f1,name));self.assertFalse(self.put(self.f2,name))
def test_bad_details_revoke_previously_confirmed_target(self):
for kwargs in ({'clipped':True},{'occluded':True},{'sharpness':0},{'scores':(('multirotor_uav',1.),)}, {'scores':scores('bird')}):
with self.subTest(kwargs=kwargs):
self.setUp();self.confirm();f=dc.replace(self.f2,seq=3,acquired_mono=10.2)
self.gate.observe(self.ctx,f,self.clock)
result=dc.replace(Semantic(f,B,scores(),100),**kwargs)
self.assertFalse(self.gate.submit(self.ctx,result,self.clock));self.assertFalse(self.gate.eligible(self.ctx,self.clock))
def test_small_original_box_cannot_be_enlarged_crop_proof(self):
f=dc.replace(self.f1,bbox=(100,100,110,110));self.gate.observe(self.ctx,f,self.clock)
self.assertFalse(self.gate.submit(self.ctx,Semantic(f,B,scores(),100),self.clock))
def test_geometry_discontinuity_revokes(self):
self.confirm();f=dc.replace(self.f2,seq=3,acquired_mono=10.2,bbox=(600,100,700,200))
self.assertFalse(self.gate.observe(self.ctx,f,self.clock));self.assertFalse(self.gate.eligible(self.ctx,self.clock))
def test_shape_change_revokes(self):
self.confirm();f=dc.replace(self.f2,seq=3,acquired_mono=10.2,shape=(1080,1920))
self.assertFalse(self.gate.observe(self.ctx,f,self.clock));self.assertFalse(self.gate.eligible(self.ctx,self.clock))
def test_revoke_lost_owner_fullstop_blocks_queued_proof(self):
self.confirm();self.gate.revoke(10);self.assertFalse(self.gate.eligible(self.ctx,self.clock))
def test_actual_visual_control_owner_tuple_accepts_finite_float(self):
context=dc.replace(self.ctx,owner=(147852,7,1793000000.125,2))
self.gate.begin(context,proposal_contract=model('generic_detector'),classifier_contract=model())
self.assertTrue(context.valid())
for value in (True,float('nan'),float('inf')):
with self.subTest(value=value):self.assertFalse(dc.replace(context,owner=(147852,7,value,2)).valid())
def test_begin_requires_verified_two_roles(self):
with self.assertRaises(ValueError):self.gate.begin(self.ctx,proposal_contract=model(),classifier_contract=model())
def test_frame_ledger_is_bounded(self):
for seq in range(1,101):self.gate.observe(self.ctx,Frame(seq,10+seq/1000,(100,100,200,200),(720,1280)),self.clock)
self.assertEqual(len(self.gate._states[10].frames),16)
class ModelTests(unittest.TestCase):
def test_preserves_legacy_numeric_names_no_fixed_wing_alias(self):
c=model('legacy_display',raw_names={0:'Fighter',1:'drone'},actual_sha=A,expected_sha=A)
self.assertEqual(c.names,('Fighter','drone'));self.assertEqual(c.role,'legacy_display')
with self.assertRaises(ValueError):model(raw_names=c.names)
def test_task_cannot_be_inferred_from_label_names(self):
for task in (None,'detect','segment'):
with self.subTest(task=task),self.assertRaises(ValueError):model(actual_task=task)
with self.assertRaises(ValueError):model('generic_detector',actual_task='classify')
def test_generic_class_zero_is_not_uav_class_zero(self):
self.assertEqual(model('generic_detector').names,('airborne_object',))
with self.assertRaises(ValueError):model('generic_detector',raw_names=['drone'])
def test_four_semantic_labels_exact_no_silent_alias(self):
for names in [('multirotor_uav','fixedwing_uav','bird','manned_aircraft'),('multirotor_uav','fixed_wing_uav','bird','civil_aircraft')]:
with self.subTest(names=names),self.assertRaises(ValueError):model(raw_names=names)
def test_format_metadata_sources_follow_checkout(self):
for path,source in [('fake.pt','loaded_model.names'),('fake.pth','result.names'),('fake.onnx','onnx.metadata.names'),('fake.onnx','result.names'),('fake.engine','result.names')]:
with self.subTest(path=path,source=source):self.assertEqual(model(path=path,metadata_source=source).names,NAMES)
def test_unsupported_format_or_metadata_fails(self):
for path,source in [('fake.tflite','result.names'),('fake.engine','loaded_model.names'),('fake.pt','config.CLASS_NAMES'),('fake.onnx','sidecar-unpinned')]:
with self.subTest(path=path,source=source),self.assertRaises(ValueError):model(path=path,metadata_source=source)
def test_duplicate_literal_keys_are_not_silently_overwritten(self):
with self.assertRaises(ValueError):contracts.normalize_names("{0: 'Fighter', 0: 'drone'}")
def test_model_hash_must_match_pin(self):
with self.assertRaises(ValueError):model(actual_sha=A)
def test_no_fallback_when_names_missing_or_ambiguous(self):
for raw in (None,{},[],{True:'x'},{0:'x','0':'y'},{'01':'x'},['bird','bird'],{0:'x',2:'y'}, {0:' x '}):
with self.subTest(raw=raw),self.assertRaises(ValueError):contracts.normalize_names(raw)
def test_onnx_literal_names_are_data_only(self):
self.assertEqual(contracts.normalize_names("{0: 'Fighter', 1: 'drone'}"),('Fighter','drone'))
with self.assertRaises(ValueError):contracts.normalize_names("__import__('os').system('false')")
class BoundaryTests(Base):
def test_unknown_false_allows_recording_but_blocks_alarm_ingress(self):
alarms.ingest_detection(10,True)
self.assertFalse(alarms.is_armed(10));self.assertTrue(state.alarm_queue.empty())
def test_verified_alarm_ingress_and_snapshot(self):
self.confirm();alarms.ingest_detection(10,True)
self.assertTrue(alarms.is_armed(10));self.assertTrue(state.alarm_queue.get_nowait()['data'])
self.assertTrue(alarms._http_queue.get_nowait()['json']['cameras'][1]['alarm'])
def test_raw_queued_boolean_or_untokened_on_denied(self):
self.confirm()
for payload in (True,'true',{'type':'video_alarm','data':True}):self.assertFalse(boundary.filter_ws(payload)['data'])
def test_smoke_cannot_arm_unknown_camera(self):
alarms.queue_alarm_mac('00:11:22:33:44:55',True)
self.assertFalse(state.alarm_queue.get_nowait()['data'])
def test_unmapped_smoke_mac_denied_even_with_other_target(self):
self.confirm();alarms.queue_alarm_mac('00:11:22:33:44:77',True)
self.assertFalse(state.alarm_queue.get_nowait()['data'])
def test_rec_active_alone_and_legacy_events_api_denied(self):
tree=ast.parse((ROOT/'ptz_tracker_modular/events.py').read_text(encoding='utf8'))
fn=next(n for n in tree.body if isinstance(n,ast.FunctionDef) and n.name=='queue_alarm')
queued=[];env={'_dispatch_alarm':queued.append,'_boundary':boundary}
exec(compile(ast.Module(body=[fn],type_ignores=[]),'events-queue','exec'),env)
env['queue_alarm'](10,True);self.assertFalse(queued[0]['data'])
def test_buffered_on_rechecked_after_expiry(self):
self.confirm();alarms.ingest_detection(10,True);queued=state.alarm_queue.get_nowait();self.clock=10.9
self.assertFalse(boundary.filter_ws(queued)['data']);self.assertFalse(alarms.is_armed(10))
def test_owner_or_stream_changed_before_send_denied(self):
self.confirm();alarms.ingest_detection(10,True);queued=state.alarm_queue.get_nowait()
self.provider[10]=dc.replace(self.ctx,owner=('manual',8,12));self.assertFalse(boundary.filter_ws(queued)['data'])
def test_old_token_cannot_use_new_confirmed_session(self):
self.confirm();alarms.ingest_detection(10,True);queued=state.alarm_queue.get_nowait()
self.ctx=dc.replace(self.ctx,inspection_id=2);self.provider[10]=self.ctx
self.gate.begin(self.ctx,proposal_contract=model('generic_detector'),classifier_contract=model());self.confirm()
self.assertFalse(boundary.filter_ws(queued)['data'])
def test_http_retry_rechecks_expiry_and_preserves_body(self):
self.confirm();alarms.ingest_detection(10,True);item=alarms._http_queue.get_nowait();self.clock=10.9
clean=boundary.filter_http(item['json'],item['_cc10_contexts'],alarms._camera_for_mac)
self.assertFalse(any(c['alarm'] for c in clean['cameras']));self.assertTrue(any(c['alarm'] for c in item['json']['cameras']))
def test_heartbeat_drops_stale_armed_state(self):
self.confirm();alarms.ingest_detection(10,True);self.clock=10.9
_,body=alarms._bulk_snapshot_for_all_cams();self.assertFalse(any(c['alarm'] for c in body['cameras']))
def test_provider_failure_and_missing_binding_fail_closed(self):
self.confirm();boundary._context_provider=lambda c:1/0
self.assertFalse(boundary.arm_allowed(10));boundary._gate=None;self.assertFalse(boundary.arm_allowed(10))
def test_off_always_passes_as_off(self):
alarms.queue_alarm_mac('00:11:22:33:44:55',False)
self.assertFalse(state.alarm_queue.get_nowait()['data'])
def test_disabled_mode_preserves_legacy(self):
cfg.UNKNOWN_INSPECTION_ENABLE=False;alarms.ingest_detection(10,True);self.assertTrue(alarms.is_armed(10))
def test_smoke_startup_is_disabled_under_unknown_mode(self):
tree=ast.parse((ROOT/'ptz_tracker_modular/main.py').read_text(encoding='utf8'))
node=next(n for n in ast.walk(tree) if isinstance(n,ast.If) and 'ALARM_SMOKE' in ast.unparse(n.test))
fake_os=types.SimpleNamespace(getenv=lambda *a:'1')
self.assertFalse(eval(compile(ast.Expression(node.test),'smoke-test','eval'),{'config':cfg,'os':fake_os}))
def run_sender(self, coroutine):
# Windows Proactor creates a TCP socketpair even for fake transports.
# Step this coroutine with a deterministic fake loop instead; no sockets.
class Loop:
tick=0.
def time(self):self.tick+=.02;return self.tick
async def run_in_executor(self, executor, fn):return fn()
async def sleep(*a):return None
loop=Loop();state.MAIN_LOOP=loop
with patch.object(asyncio,'get_running_loop',return_value=loop),patch.object(asyncio,'sleep',sleep):
with self.assertRaises(asyncio.CancelledError):coroutine.send(None)
def test_heartbeat_internal_transport_retries_disabled_in_unknown_mode(self):
tree=ast.parse((ROOT/'ptz_tracker_modular/alarms.py').read_text(encoding='utf8'))
fn=next(n for n in tree.body if isinstance(n,ast.AsyncFunctionDef) and n.name=='periodic_status_sender')
condition=next(n.test for n in ast.walk(fn) if isinstance(n,ast.If) and 'Retry is not None' in ast.unparse(n.test))
self.assertFalse(eval(compile(ast.Expression(condition),'retry-policy','eval'),{'Retry':object(),'_boundary':boundary}))
def test_actual_ws_sender_filters_queued_on(self):
self.confirm();alarms.ingest_detection(10,True);self.clock=10.9
sent=[]
class WS:
async def __aenter__(self):return self
async def __aexit__(self,*a):return False
async def send(self,payload):sent.append(json.loads(payload));raise asyncio.CancelledError
fake=types.ModuleType('websockets');fake.connect=lambda *a,**k:WS()
with patch.dict(sys.modules,{'websockets':fake}):self.run_sender(alarms.alarm_sender())
self.assertEqual(sent,[{'type':'video_alarm','data':False}])
def test_actual_http_sender_filters_queued_on(self):
self.confirm();alarms.ingest_detection(10,True);self.clock=10.9;sent=[]
class Session:
def mount(self,*a):pass
def post(self,url,**kw):sent.append(kw['json']);raise asyncio.CancelledError
req=types.ModuleType('requests');req.Session=Session
adapters=types.ModuleType('requests.adapters');adapters.HTTPAdapter=lambda **kw:object()
with patch.dict(sys.modules,{'requests':req,'requests.adapters':adapters}):self.run_sender(alarms.alarm_http_sender())
self.assertEqual(len(sent),1);self.assertFalse(any(c['alarm'] for c in sent[0]['cameras']))
if __name__=='__main__':
import socket
# Any accidental real socket attempt fails this run. Fake senders above do not
# instantiate model.py/main.py/streaming.py or contact actual services.
with patch.object(socket,'create_connection',side_effect=AssertionError('network forbidden')):
suite=unittest.defaultTestLoader.loadTestsFromModule(sys.modules[__name__])
result=unittest.TextTestRunner(verbosity=2).run(suite)
raise SystemExit(not result.wasSuccessful())

@ -1,67 +0,0 @@
import ast
import asyncio
from pathlib import Path
import sys
from types import SimpleNamespace
import unittest
from unittest.mock import patch
import test_alarm_transport as transport
from cc10_offline import inspection_handoff
def forbid_network(event, args):
if event.startswith("socket."):
raise RuntimeError("network forbidden")
sys.addaudithook(forbid_network)
class CompositionTests(transport.Base):
def test_configured_handoff_guard_controls_real_queued_egress(self):
self.confirm()
bridge = SimpleNamespace(gate=self.gate, active_context=lambda cam: self.provider.get(cam))
adapter = inspection_handoff.Handoff(bridge, camera_epoch=lambda cam: 1,
latest_visual=lambda cam, now: None)
self.addCleanup(setattr, inspection_handoff, "_configured", None)
inspection_handoff.configure(adapter)
transport.alarms.ingest_detection(10, True)
ws = transport.state.alarm_queue.get_nowait()
http = transport.alarms._http_queue.get_nowait()
self.assertTrue(transport.boundary.filter_ws(ws)["data"])
self.provider.clear()
self.assertFalse(transport.boundary.filter_ws(ws)["data"])
result = transport.boundary.filter_http(
http["json"], http["_cc10_contexts"], transport.alarms._camera_for_mac)
self.assertFalse(any(cam["alarm"] for cam in result["cameras"]))
def test_recording_loop_is_excluded_only_in_unknown_mode(self):
tree = ast.parse((Path(__file__).parent / "ptz_tracker_modular/streaming.py")
.read_text(encoding="utf-8"))
fn = next(node for node in tree.body if isinstance(node, ast.AsyncFunctionDef)
and node.name == "alarm_gate_loop")
transport.cfg.CAMERA_CONFIG = {10: {}}
sent = []
decisions = []
def legacy_gate(cam, recording):
decisions.append((cam, recording))
return recording
async def end_iteration(*args):
raise asyncio.CancelledError
env = dict(config=transport.cfg,
state=SimpleNamespace(ptz_states={10: {"rec_active": True}}),
alarms=SimpleNamespace(queue_alarm=lambda *args: sent.append(args)),
alarm_boundary=transport.boundary, _alarm_gate=legacy_gate,
log_main=transport.logging.getLogger("test"), asyncio=asyncio)
exec(compile(ast.Module(body=[fn], type_ignores=[]), "alarm_gate_loop", "exec"), env)
for enabled, expected in ((True, []), (False, [(10, True)])):
transport.cfg.UNKNOWN_INSPECTION_ENABLE = enabled
sent.clear()
decisions.clear()
with patch.object(asyncio, "sleep", end_iteration):
with self.assertRaises(asyncio.CancelledError):
env["alarm_gate_loop"]().send(None)
self.assertEqual(sent, expected)
self.assertEqual(decisions, expected)
if __name__ == "__main__":
unittest.main(verbosity=2)

@ -1,278 +0,0 @@
"""New exact adapter + checkout handoff checks; no old suites or model imports."""
import ast
from contextlib import nullcontext, contextmanager
import hashlib
import importlib.util
import io
import json
from pathlib import Path
import sys
import threading
from types import ModuleType, SimpleNamespace
import unittest
import numpy as np
sys.dont_write_bytecode = True
HERE = Path(__file__).resolve().parent
package = ModuleType('ptz_tracker_modular'); package.__path__=[str(HERE/'ptz_tracker_modular')]
sys.modules[package.__name__] = package
config = ModuleType('ptz_tracker_modular.config'); config.UNKNOWN_INSPECTION_ENABLE=True
sys.modules[config.__name__] = config
from ptz_tracker_modular import inspection_handoff as wiring
from ptz_tracker_modular.inspection_bridge import InspectionBridge
from ptz_tracker_modular.unknown_inspection import Settings, Session
from ptz_tracker_modular.model_class_contract import ModelContract
from ptz_tracker_modular.inspection_runtime import CropContext, source_key
from ptz_tracker_modular import alarm_boundary
class Future:
def __init__(self): self.finished=False; self.value='unset'
def done(self): return self.finished
def set_result(self,value): self.finished=True; self.value=value
def checkout_functions(path, namespace):
tree=ast.parse(path.read_text(encoding='utf8'))
names={'_refresh_inference_item','_prepare_visual_inference_item','_postprocess_inference_item'}
nodes=[n for n in tree.body if isinstance(n,ast.FunctionDef) and n.name in names]
assert {n.name for n in nodes}==names
tree=ast.Module(body=[ast.ImportFrom(module='__future__',names=[ast.alias(name='annotations')],level=0)]+nodes,type_ignores=[])
exec(compile(ast.fix_missing_locations(tree),str(path),'exec'),namespace)
return namespace
class HandoffTests(unittest.TestCase):
def setUp(self):
self.st=dict(generation=4,track_started_at=99.,mode='TRACK',tracking_active=True)
self.states={0:self.st};self.epoch=1;self.now=50.;self.utc=100.;self.saved=None
self.lock=threading.RLock();self.calls=[]
self.owner=lambda st:(id(st),st['generation'],st['track_started_at'],0)
cfg=Settings('a'*64,'b'*64,('airborne_object',),.25,.8,.2,16,10.,5.,enabled=True)
proposal=ModelContract('a'*64,'.pt',('airborne_object',),'generic_detector','loaded_model.names','detect')
semantic=ModelContract('b'*64,'.pt',('multirotor_uav','fixed_wing_uav','bird','manned_aircraft'),'semantic_classifier','loaded_model.names','classify')
self.bridge=InspectionBridge(settings=cfg,cameras=(0,),proposal_contract=proposal,
classifier_contract=semantic,owner=self.owner,control_lock=lambda c:self.lock,
controller=lambda *a,**k:self.calls.append((a,k)),alarm_ready=lambda st:False,
state_provider=lambda c:self.states[c],clock=lambda:self.now)
self.adapter=wiring.Handoff(self.bridge,camera_epoch=lambda c:self.epoch,
latest_visual=lambda c,now:self.saved,mono_ns=lambda:round(self.now*1e9),utc_ns=lambda:round(self.utc*1e9))
wiring.configure(self.adapter)
self.addCleanup(setattr,wiring,'_configured',None)
self.addCleanup(setattr,config,'UNKNOWN_INSPECTION_ENABLE',True)
self.assertTrue(self.adapter.begin_source(0,'cpp_image','conn1',self.epoch))
self.hooks=checkout_functions(HERE/'ptz_tracker_modular/streaming.py',dict(
inspection_handoff=wiring,state=SimpleNamespace(ptz_states=self.states),
visual_control=SimpleNamespace(enabled=lambda:False),
postprocess_control=lambda *a,**k:self.calls.append((a,k))))
def accepted(self,seq=1):
image=np.random.default_rng(seq).integers(0,256,(64,64,3),dtype=np.uint8)
return self.adapter.accepted(0,image,seq,self.epoch)
def item(self,ticket):
item=(0,ticket.pixels,True,ticket.stamp.source_seq,Future(),7.)
self.assertTrue(self.adapter.bind_item(item,ticket));return item
def advance(self,seconds): self.now+=seconds;self.utc+=seconds
def test_accepted_keeps_decode_stamp_and_never_invents_capture_utc(self):
t=self.accepted();self.assertEqual(t.stamp.decode_mono_ns,50_000_000_000)
self.assertEqual(t.stamp.decode_utc_ns,100_000_000_000)
self.assertIsNone(t.stamp.capture_utc_ns);self.assertIsNone(t.stamp.raw_pts)
self.assertFalse(self.st['inspection_authorized'])
self.assertEqual(t.acquired_owner,self.owner(self.st))
def test_exact_checkout_refresh_atomically_replaces_pixels_seq_stamp_owner(self):
old=self.accepted();item=self.item(old);self.advance(.05);new=self.accepted(2)
self.assertTrue(self.adapter.pending(new))
updated,changed=self.hooks['_refresh_inference_item'](item)
self.assertTrue(changed);self.assertIs(updated[1],new.pixels)
self.assertEqual(updated[3],2);self.assertIs(updated[4].inspection_ticket,new)
self.assertIsNone(updated[4].visual_sample);self.assertNotIn('pending_frame',self.st)
self.assertEqual(new.stamp.decode_mono_ns,50_050_000_000)
def test_mismatched_pending_pixel_ticket_is_dropped_without_restamping(self):
old=self.accepted();item=self.item(old);self.advance(.05);new=self.accepted(2)
self.adapter.pending(new);self.st['pending_frame']=new.pixels.copy()
updated,changed=self.hooks['_refresh_inference_item'](item)
self.assertFalse(changed);self.assertIs(updated[4].inspection_ticket,old)
self.assertNotIn('pending_frame',self.st)
def test_stale_pending_and_expired_batch_are_dropped_before_inference(self):
old=self.accepted();item=self.item(old);self.adapter.pending(old);self.advance(.651)
self.hooks['_refresh_inference_item'](item)
self.assertNotIn('pending_inspection_ticket',self.st)
self.assertEqual(self.adapter.prune([item]),[])
self.assertTrue(item[4].done());self.assertIsNone(item[4].value)
def test_pair_replaces_whole_ticket_with_exact_retained_image(self):
old=self.accepted();item=self.item(old);self.advance(.05);new=self.accepted(2)
sample=self.adapter.visual_sample(new,SimpleNamespace(source_seq=2,ok=True))
self.saved=(new.pixels,sample)
paired=self.hooks['_prepare_visual_inference_item'](item)
self.assertIs(paired[1],new.pixels);self.assertEqual(paired[3],2)
self.assertIs(paired[4].inspection_ticket,new);self.assertIs(paired[4].visual_sample,sample)
def test_pair_wrong_pixels_or_expired_visual_cannot_replace_packet(self):
old=self.accepted();item=self.item(old)
sample=self.adapter.visual_sample(old,SimpleNamespace(source_seq=1,ok=True))
self.saved=(old.pixels.copy(),sample)
self.assertIs(self.hooks['_prepare_visual_inference_item'](item)[1],old.pixels)
self.advance(.251);self.saved=(old.pixels,sample)
self.assertIsNone(self.adapter.visual_sample(old,SimpleNamespace(source_seq=1)))
self.assertIs(self.hooks['_prepare_visual_inference_item'](item)[4].inspection_ticket,old)
def test_postprocess_over_650ms_or_old_owner_never_calls_controller(self):
item=self.item(self.accepted());self.advance(.651)
self.assertFalse(self.hooks['_postprocess_inference_item'](*item[:2],None,*item[2:5]))
self.assertFalse(self.calls)
self.st['generation']+=1
self.assertFalse(self.adapter.current(item[4].inspection_ticket))
def test_fullstop_and_manual_revoke_before_existing_transition_without_regrant(self):
for reason in ('FULLSTOP','manual'):
t=self.accepted(1 if reason=='FULLSTOP' else 2)
self.st['inspection_authorized']=True
self.st['zoom_no_effect_count']=3
session=Session(0,9,self.owner(self.st),49.,55.,phase='inspection')
self.st['inspection_session']=session;self.adapter.pending(t)
called=[]
def existing():
called.append(True);self.assertFalse(self.st['inspection_authorized'])
self.assertEqual(session.phase,'closed');self.st['mode']='MANUAL'
self.assertTrue(self.adapter.transition(0,self.st,t.acquired_owner,reason,existing))
self.assertTrue(called);self.assertFalse(self.adapter.current(t))
self.assertEqual(session.deadline_mono,55.);self.assertEqual(self.st['zoom_no_effect_count'],3)
self.assertNotIn('pending_frame',self.st)
self.advance(.01)
def test_same_owner_revoke_rebind_aba_cannot_revive_old_future(self):
t=self.accepted();item=self.item(t);owner=t.acquired_owner
self.assertTrue(self.adapter.transition(0,self.st,owner,'FULLSTOP',lambda:None))
self.st['inspection_authorized']=True # explicit external fresh grant for test
self.assertEqual(self.owner(self.st),owner)
self.advance(.01);new=self.accepted(2)
self.assertTrue(self.adapter.current(new));self.assertFalse(self.adapter.current(t))
self.assertEqual(self.adapter.prune([item]),[])
def test_foreign_retired_state_transition_cannot_revoke_current_state(self):
old=self.st.copy();self.st['inspection_authorized']=True
self.assertFalse(self.adapter.transition(0,old,self.owner(old),'FULLSTOP',lambda:self.fail('transition called')))
self.assertTrue(self.st['inspection_authorized'])
def test_reconnect_and_camera_lifecycle_epoch_drop_old_ticket(self):
t=self.accepted();self.adapter.begin_source(0,'cpp_image','conn2',self.epoch)
self.assertFalse(self.adapter.current(t));self.assertFalse(self.st['inspection_authorized'])
new=self.accepted(1);self.epoch+=1
self.assertFalse(self.adapter.current(new));self.assertIsNone(self.adapter.accepted(0,new.pixels,2,self.epoch))
def test_source_utc_clock_jump_revokes_original_binding_without_retimestamp(self):
old=self.accepted();self.advance(.1);self.utc+=2.;new=self.accepted(2)
self.assertEqual(new.stamp.clock_epoch,1);self.assertFalse(self.adapter.current(old))
self.assertFalse(self.st['inspection_authorized'])
def test_slow_recognition_does_not_block_exact_checkout_control_handoff(self):
t=self.accepted();item=self.item(t);ctx=CropContext(0,1,t.acquired_owner,source_key(t.stamp),'b'*64)
self.bridge.crops.bind(ctx)
self.assertTrue(self.bridge.crops.submit(ctx,t.stamp,t.pixels,(8.,8.,48.,48.),now=self.now,occluded=False))
entered,release=threading.Event(),threading.Event()
def classify(pixels):
entered.set();release.wait(2)
return (('multirotor_uav',.94),('fixed_wing_uav',.02),('bird',.02),('manned_aircraft',.02))
thread=threading.Thread(target=lambda:self.bridge.crops.run_one(classify,clock=lambda:self.now))
thread.start()
try:
self.assertTrue(entered.wait(1))
# This is the real copied checkout wrapper and actual bridge, not
# classifier completion. No observation is supplied, so no grant.
self.hooks['_postprocess_inference_item'](0,t.pixels,SimpleNamespace(names={0:'airborne_object'},boxes=None),True,1,item[4])
self.assertEqual(len(self.calls),1)
finally:
release.set();thread.join(2)
self.assertFalse(thread.is_alive())
def test_disabled_checkout_handoff_calls_legacy_controller_unchanged(self):
config.UNKNOWN_INSPECTION_ENABLE=False
item=(0,np.zeros((4,4,3),dtype=np.uint8),True,8,Future(),7.)
self.assertIs(self.hooks['_prepare_visual_inference_item'](item),item)
self.assertEqual(self.hooks['_refresh_inference_item'](item),(item,False))
self.hooks['_postprocess_inference_item'](0,item[1],'legacy',True,8,item[4])
self.assertEqual(self.calls[-1][0][2],'legacy')
def test_unknown_startup_and_unbound_alarm_fail_closed(self):
wiring._configured=None
with self.assertRaises(RuntimeError): wiring.require_configured()
self.assertFalse(alarm_boundary.arm_allowed(0))
def test_recognition_diagnostics_are_original_decode_age_and_revoke_clears(self):
t=self.accepted();ctx=CropContext(0,1,t.acquired_owner,source_key(t.stamp),'b'*64)
self.bridge.crops.bind(ctx)
self.bridge.crops.submit(ctx,t.stamp,t.pixels,(8.,8.,48.,48.),now=self.now,occluded=False)
self.advance(.1)
def classify(pixels):
self.advance(.2)
return (('multirotor_uav',.94),('fixed_wing_uav',.02),('bird',.02),('manned_aircraft',.02))
self.assertTrue(self.bridge.crops.run_one(classify,clock=lambda:self.now))
ages=self.bridge.crops.decode_ages()[0]
self.assertAlmostEqual(ages['recognition_start'],.1)
self.assertAlmostEqual(ages['recognition_complete'],.3)
self.bridge.crops.revoke(0)
self.assertEqual(self.bridge.crops.decode_ages(),{})
def test_transition_between_outer_check_and_bridge_admission_rejects_old_future(self):
t=self.accepted();item=self.item(t);interposed=[False]
@contextmanager
def locked(camera):
with self.lock:
if not interposed[0]:
interposed[0]=True
def new_discovery():
self.st['inspection_authorized']=True
self.st['inspection_session']=Session(0,2,self.owner(self.st),50.,55.,
phase='inspection',bbox=(8.,8.,48.,48.),shape=(64,64),contract=self.bridge.settings)
self.adapter.transition(0,self.st,t.acquired_owner,'FULLSTOP',new_discovery)
yield
self.bridge.control_lock=locked
result=SimpleNamespace(names={0:'airborne_object'},boxes=None)
self.assertFalse(self.hooks['_postprocess_inference_item'](0,t.pixels,result,True,1,item[4]))
self.assertTrue(interposed[0]);self.assertFalse(self.calls)
self.assertTrue(self.st['inspection_authorized']) # old callback does not revoke new discovery
def test_prepare_foreign_camera_future_cannot_consult_or_pair_other_camera(self):
t=self.accepted();item=self.item(t)
self.adapter.latest_visual=lambda *a:self.fail('foreign camera consulted retained image')
foreign=(2,item[1],True,item[3],item[4],item[5])
self.assertIs(self.adapter.prepare(foreign),foreign)
def test_decode_receipt_does_not_hide_800ms_control_lock_wait(self):
@contextmanager
def delayed(camera):
self.advance(.8)
with self.lock: yield
self.bridge.control_lock=delayed
self.assertIsNone(self.accepted())
def test_decode_receipt_preserves_original_clock_across_short_lock_wait(self):
@contextmanager
def delayed(camera):
self.advance(.2)
with self.lock: yield
self.bridge.control_lock=delayed
ticket=self.accepted()
self.assertEqual(ticket.stamp.decode_mono_ns,50_000_000_000)
self.assertEqual(ticket.stamp.decode_utc_ns,100_000_000_000)
self.assertAlmostEqual(self.now-ticket.stamp.decode_mono_ns/1e9,.2)
def test_decode_receipt_cannot_bless_owner_changed_while_waiting(self):
@contextmanager
def changed(camera):
self.advance(.1);self.st['generation']+=1
with self.lock: yield
self.bridge.control_lock=changed
self.assertIsNone(self.accepted())
if __name__ == '__main__':
unittest.main(verbosity=2)

@ -1,122 +0,0 @@
"""Exercise production decoder, MicroBatcher and provenance with fake I/O."""
import asyncio
import logging
from pathlib import Path
import time
from types import SimpleNamespace
import unittest
from typing import Any, List, Optional, Tuple
from uuid import uuid4
import numpy as np
import test_handoff as fixture
from ptz_tracker_modular import inspection_handoff as wiring
class ServerPathTests(unittest.IsolatedAsyncioTestCase):
def setUp(self):
self.fx = fixture.HandoffTests()
self.fx.setUp()
self.addCleanup(self.fx.doCleanups)
self.state = self.fx.st
self.adapter = self.fx.adapter
self.adapter.detect = lambda frames: [None] * len(frames)
self.config = fixture.config
self.config.UNKNOWN_INSPECTION_ENABLE = True
self.config.CAMERA_CONFIG = {0: {}}
self.config.PTZ_CAM_IDS = (0,)
self.config.CPP_WS_URI = 'offline'
self.config.ADAPTIVE_BATCH_ENABLE = False
self.config.BATCH_MIN = self.config.BATCH_MAX = 1
self.config.BATCH_TARGET_MS = 1
self.config.SAHI_ENABLE = True # Forbidden for UNKNOWN provenance.
self.server_state = SimpleNamespace(ptz_states={0: self.state}, detected_cameras={0},
video_clients=set())
self.env = dict(
asyncio=asyncio, time=time, np=np, cv2=SimpleNamespace(IMREAD_COLOR=1,
imdecode=lambda data, mode: np.full((16, 16, 3), int(data[0]), dtype=np.uint8)),
logger=logging.getLogger('server-path'), config=self.config, state=self.server_state,
uuid4=uuid4, inspection_handoff=wiring, Optional=Optional,
Any=Any, Tuple=Tuple, List=List, InferenceItem=tuple,
_resolve_cpp_cam_id=int, _cpp_stream_map_logged=set(), ensure_runtime_state_for_camera=lambda cam: None,
_has_recent_video_client=lambda now: False, _frontend_raw_preview_due=lambda *args: False,
_target_predecode_fps=lambda *args: 0, _target_infer_fps=lambda *args: 0,
_select_inference_batch=lambda items, size, **kw: (items[:size], items[size:]),
visual_control=SimpleNamespace(enabled=lambda: True),
postprocess_control=lambda *args, **kw: self.fail('Legacy controller used in UNKNOWN'),
sahi_augment_batch=lambda *args: self.fail('SAHI used in UNKNOWN'),
yolo_forward=lambda *args: self.fail('Legacy detector used in UNKNOWN'),
)
self.state['proc_busy'] = False
self.load('cpp_ws_loop', 'MicroBatcher', '_refresh_inference_item',
'_prepare_visual_inference_item', '_postprocess_inference_item')
def load(self, *names):
import ast
path = Path(__file__).parent / 'ptz_tracker_modular/streaming.py'
tree = ast.parse(path.read_text(encoding='utf-8'))
definitions = [node for node in tree.body if getattr(node, 'name', None) in names]
exec(compile(ast.Module(body=definitions, type_ignores=[]), str(path), 'exec'), self.env)
async def test_decoder_batch_passes_exact_pixels_ticket_and_owner(self):
seen = asyncio.Event()
called = []
original = self.adapter.process_item
def capture(cam, pixels, result, is_ptz, seq, future):
ticket = future.inspection_ticket
called.append((cam, pixels, is_ptz, seq, ticket, self.adapter.current(ticket)))
loop.call_soon_threadsafe(seen.set)
return True
self.adapter.process_item = capture
loop = asyncio.get_running_loop()
batcher = self.env['MicroBatcher'](max_batch=1)
self.server_state.batcher = batcher
class Socket:
async def __aenter__(self):
return self
async def __aexit__(self, *args):
pass
async def __aiter__(self):
yield b'\x01\x00\x00\x17'
await asyncio.Future()
self.env['websockets'] = SimpleNamespace(connect=lambda *args, **kwargs: Socket())
ws = asyncio.create_task(self.env['cpp_ws_loop']())
try:
try:
await asyncio.wait_for(seen.wait(), 2)
except TimeoutError:
self.fail((self.state.get('last_source_seq'), self.state.get('inspection_decode_age_s'), self.state.get('proc_busy'), ws.done(), batcher._task.exception() if batcher._task.done() else batcher._task.get_stack()))
cam, pixels, ptz, seq, ticket, current = called.pop()
self.assertEqual((cam, ptz, seq, int(pixels[0, 0, 0])), (0, True, 1, 23))
self.assertTrue(current)
self.assertIs(ticket.pixels, pixels)
self.assertEqual(ticket.acquired_owner, self.adapter.bridge.owner(self.state))
finally:
ws.cancel()
batcher._task.cancel()
await asyncio.gather(ws, batcher._task, return_exceptions=True)
self.adapter.process_item = original
self.assertFalse(self.adapter.current(ticket))
self.assertFalse(self.state['inspection_authorized'])
async def test_mismatched_ticket_does_not_enter_batch(self):
batcher = self.env['MicroBatcher'](max_batch=1)
try:
ticket = self.fx.accepted()
await batcher.submit(0, ticket.pixels.copy(), True,
source_seq=ticket.stamp.source_seq, inspection_ticket=ticket)
self.assertEqual(batcher._buf, [])
finally:
batcher._task.cancel()
await asyncio.gather(batcher._task, return_exceptions=True)
if __name__ == '__main__':
unittest.main(verbosity=2)

@ -1,69 +0,0 @@
"""One common veto for alarm entry, buffered sends, retries and heartbeat.
Bind only after real producer/model/owner integration. No binding means no ON in
UNKNOWN mode. Context provider must return None unless the active V2 Session also
allows alarm; this guard is an additional veto, never a replacement for Session.
"""
from copy import deepcopy
import time
from . import config
from .alarm_eligibility import AlarmEligibility, Context
_gate = None
_context_provider = None
def enabled():
return bool(getattr(config, 'UNKNOWN_INSPECTION_ENABLE', False))
def bind_guard(gate, context_provider):
global _gate, _context_provider
if not isinstance(gate, AlarmEligibility) or not callable(context_provider):
raise ValueError('An explicit guard and active-session context provider are required')
_gate, _context_provider = gate, context_provider
def capture_contexts(camera_ids):
if not enabled():
return None
result = {}
for camera in camera_ids:
try:
ctx = _context_provider(camera) if _context_provider else None
if (isinstance(ctx, Context) and ctx.camera == camera
and _gate and _gate.eligible(ctx, time.monotonic())):
result[camera] = ctx
except Exception:
pass
return result
def arm_allowed(camera, requested=True, contexts=None):
if not requested:
return False
if not enabled():
return True
current = capture_contexts((camera,)).get(camera)
return current is not None and (contexts is None or contexts.get(camera) == current)
def filter_ws(payload):
if not enabled():
return payload
# Every buffered ON must have an enqueue-time provenance token. Old queued
# booleans, strings and startup/smoke writes cannot acquire a token later.
if not isinstance(payload, dict):
return {'type': 'video_alarm', 'data': False}
contexts = payload.get('_cc10_contexts')
allowed = isinstance(contexts, dict) and any(arm_allowed(c, True, contexts) for c in contexts)
return {'type': payload.get('type', 'video_alarm'), 'data': bool(payload.get('data')) and allowed}
def filter_http(body, contexts, mac_to_camera):
if not enabled():
return body
out = deepcopy(body)
for camera in out.get('cameras') or []:
cid = mac_to_camera(camera.get('mac'))
camera['alarm'] = bool(camera.get('alarm')) and isinstance(contexts, dict) and cid is not None and arm_allowed(cid, True, contexts)
return out

@ -1,187 +0,0 @@
"""Offline candidate: original-frame semantic evidence, never record/track score.
All times are local monotonic acquisition times from the producer, not inference
completion or wall UTC. No model, network, camera or filesystem operations.
"""
from dataclasses import dataclass, field
from math import isfinite
from threading import RLock
TARGETS = frozenset(('multirotor_uav', 'fixed_wing_uav'))
NAMES = TARGETS | {'bird', 'manned_aircraft'}
def finite(*values):
return all(type(v) in (int, float) and isfinite(v) for v in values)
def sha(value):
return isinstance(value, str) and len(value) == 64 and all(c in '0123456789abcdef' for c in value)
@dataclass(frozen=True)
class Context:
camera: int
inspection_id: int
owner: tuple
source_id: str # producer stream/epoch identity; changes on reconnect
proposal_sha: str
classifier_sha: str
def valid(self):
return (type(self.camera) is int and self.camera >= 0
and type(self.inspection_id) is int and self.inspection_id > 0
and type(self.owner) is tuple and bool(self.owner)
and all((type(v) is str and bool(v)) or finite(v) for v in self.owner)
and isinstance(self.source_id, str) and 0 < len(self.source_id) <= 128
and sha(self.proposal_sha) and sha(self.classifier_sha))
@dataclass(frozen=True)
class Frame:
seq: int
acquired_mono: float
bbox: tuple
shape: tuple # original (height, width), never resized crop shape
def valid(self, now):
if not (type(self.seq) is int and self.seq > 0
and finite(now, self.acquired_mono) and 0 <= now-self.acquired_mono <= .65
and type(self.shape) is tuple and len(self.shape) == 2
and all(type(v) is int and v > 0 for v in self.shape)
and type(self.bbox) is tuple and len(self.bbox) == 4 and finite(*self.bbox)):
return False
x1, y1, x2, y2 = self.bbox
return 0 <= x1 < x2 <= self.shape[1] and 0 <= y1 < y2 <= self.shape[0]
def same_object(a, b):
# Same bounded continuity as the retained V1 policy; never semantic identity.
area_a = (a.bbox[2]-a.bbox[0])*(a.bbox[3]-a.bbox[1])
area_b = (b.bbox[2]-b.bbox[0])*(b.bbox[3]-b.bbox[1])
jump = max(abs(a.bbox[0]+a.bbox[2]-b.bbox[0]-b.bbox[2])/(2*b.shape[1]),
abs(a.bbox[1]+a.bbox[3]-b.bbox[1]-b.bbox[3])/(2*b.shape[0]))
return .3 <= area_a/area_b <= 3.33 and jump <= .035
@dataclass(frozen=True)
class Semantic:
frame: Frame
classifier_sha: str
scores: tuple
sharpness: float
clipped: bool = False
occluded: bool = False
@dataclass
class _Evidence:
context: Context
frames: dict = field(default_factory=dict)
latest: Frame | None = None
semantic_seq: int = 0
votes: list = field(default_factory=list)
class AlarmEligibility:
def __init__(self, *, semantic_min=.8, margin=.2, min_side=32, sharpness_min=50):
if not (finite(semantic_min, margin, min_side, sharpness_min)
and 0 < semantic_min <= 1 and 0 < margin <= 1
and min_side > 0 and sharpness_min >= 0):
raise ValueError('Invalid recognition thresholds')
# These are offline examples, not calibrated production values.
self.thresholds = semantic_min, margin, min_side, sharpness_min
self._states = {}
self._lock = RLock()
def begin(self, context, *, proposal_contract, classifier_contract):
if not isinstance(context, Context) or not context.valid():
raise ValueError('Validated source/model/owner context required')
from .model_class_contract import ModelContract
if not (isinstance(proposal_contract, ModelContract) and isinstance(classifier_contract, ModelContract)
and proposal_contract.task == 'detect' and classifier_contract.task == 'classify'
and proposal_contract.role == 'generic_detector' and proposal_contract.names == ('airborne_object',)
and classifier_contract.role == 'semantic_classifier' and set(classifier_contract.names) == NAMES
and proposal_contract.sha256 == context.proposal_sha
and classifier_contract.sha256 == context.classifier_sha):
raise ValueError('Verified generic and classifier contracts required')
with self._lock:
self._states[context.camera] = _Evidence(context)
def revoke(self, camera):
with self._lock:
self._states.pop(camera, None)
def _state(self, context):
if not isinstance(context, Context) or not context.valid():
return None
st = self._states.get(context.camera)
return st if st and st.context == context else None
def observe(self, context, frame, now):
with self._lock:
st = self._state(context)
if not st:
return False
if (not isinstance(frame, Frame) or not frame.valid(now)
or (st.latest and (frame.seq <= st.latest.seq
or frame.acquired_mono <= st.latest.acquired_mono
or frame.shape != st.latest.shape
or not same_object(st.latest, frame)))):
st.votes.clear()
return False
# Caller supplies only accepted same-object observations; discontinuity
# or lost object must revoke before another track is admitted.
if st.latest and frame.acquired_mono-st.latest.acquired_mono > .65:
st.votes.clear()
st.latest = frame
st.frames[frame.seq] = frame
st.frames = {k: v for k, v in st.frames.items() if 0 <= now-v.acquired_mono <= .65}
while len(st.frames) > 16:
del st.frames[min(st.frames)]
return True
def submit(self, context, result, now):
with self._lock:
st = self._state(context)
if not st:
return False
valid = (isinstance(result, Semantic) and isinstance(result.frame, Frame)
and result.frame.valid(now) and result.classifier_sha == context.classifier_sha
and st.frames.get(result.frame.seq) == result.frame
and result.frame.seq > st.semantic_seq)
if not valid:
st.votes.clear()
return False
st.semantic_seq = result.frame.seq
scores = result.scores
good = (type(scores) is tuple and len(scores) == len(NAMES)
and all(type(p) is tuple and len(p) == 2 and isinstance(p[0], str)
and finite(p[1]) and 0 <= p[1] <= 1 for p in scores)
and {p[0] for p in scores} == NAMES
and abs(sum(p[1] for p in scores)-1) <= 1e-4
and result.clipped is False and result.occluded is False
and finite(result.sharpness))
min_score, margin, min_side, sharpness_min = self.thresholds
good = (good and min(result.frame.bbox[2]-result.frame.bbox[0],
result.frame.bbox[3]-result.frame.bbox[1]) >= min_side
and result.sharpness >= sharpness_min)
ranked = sorted(scores, key=lambda p: p[1], reverse=True) if good else []
if not ranked or ranked[0][1] < min_score or ranked[0][1]-ranked[1][1] < margin:
st.votes.clear()
return False
name = ranked[0][0]
if name not in TARGETS:
st.votes.clear()
return False
if st.votes and (name != st.votes[-1][0]
or not 0 < result.frame.acquired_mono-st.votes[-1][1].acquired_mono <= .65):
st.votes.clear()
st.votes.append((name, result.frame))
st.votes = st.votes[-2:]
return self.eligible(context, now)
def eligible(self, context, now):
with self._lock:
st = self._state(context)
return bool(st and st.latest and st.latest.valid(now) and len(st.votes) == 2
and all(frame.valid(now) for _, frame in st.votes))

@ -1,267 +0,0 @@
"""Offline CC-11 metadata adapter. No camera, model, network or filesystem I/O.
Caller supplies existing source_seq; this module never invents capture timestamps.
Instances belong to one producer/consumer and must not be shared between threads.
"""
from collections import deque
from dataclasses import asdict, dataclass
from fractions import Fraction
import json
import re
NS = 1_000_000_000
def integer(value, name, minimum=None):
if type(value) is not int or (minimum is not None and value < minimum):
raise ValueError(name)
return value
def identifier(value):
if not isinstance(value, str) or re.fullmatch(r"[A-Za-z0-9_-]{1,96}", value) is None:
raise ValueError("opaque identifier required; URLs/credentials are forbidden")
return value
def timebase(num, den):
return Fraction(integer(num, "tb_num", 1), integer(den, "tb_den", 1))
@dataclass(frozen=True)
class FrameStamp:
camera_id: int
source_id: str
stream_epoch: str
source_seq: int
origin_id: str | None
raw_pts: int | None
raw_dts: int | None
tb_num: int | None
tb_den: int | None
decode_mono_ns: int
decode_utc_ns: int
decode_utc_uncertainty_ns: int | None
clock_epoch: int
capture_utc_ns: int | None = None
capture_utc_uncertainty_ns: int | None = None
capture_anchor_id: str | None = None
def __post_init__(self):
for v in (self.source_id, self.stream_epoch):
identifier(v)
if self.origin_id is not None:
identifier(self.origin_id)
for name in ("camera_id", "decode_mono_ns", "decode_utc_ns", "clock_epoch"):
integer(getattr(self, name), name, 0)
integer(self.source_seq, "source_seq", 1)
if (self.tb_num is None) != (self.tb_den is None):
raise ValueError("partial timebase")
if self.tb_num is not None:
timebase(self.tb_num, self.tb_den)
for name in ("raw_pts", "raw_dts"):
if getattr(self, name) is not None:
integer(getattr(self, name), name)
if self.tb_num is None:
raise ValueError("timestamp without timebase")
for name in ("decode_utc_uncertainty_ns", "capture_utc_uncertainty_ns"):
if getattr(self, name) is not None:
integer(getattr(self, name), name, 0)
capture_fields = (self.capture_utc_ns, self.capture_utc_uncertainty_ns, self.capture_anchor_id)
if any(x is not None for x in capture_fields):
if any(x is None for x in capture_fields):
raise ValueError("partial capture anchor")
integer(self.capture_utc_ns, "capture_utc_ns", 0)
identifier(self.capture_anchor_id)
@dataclass(frozen=True)
class CaptureAnchor:
"""Externally verified source-clock anchor, NOT host receive/decode UTC.
Bounds and drift must come from a measured camera clock contract. This class
validates structure, not the truth of that external measurement.
"""
anchor_id: str
source_id: str
stream_epoch: str
pts: int
tb_num: int
tb_den: int
utc_ns: int
uncertainty_ns: int
valid_pts_min: int
valid_pts_max: int
max_drift_ppm: int
def __post_init__(self):
for v in (self.anchor_id, self.source_id, self.stream_epoch):
identifier(v)
timebase(self.tb_num, self.tb_den)
for name in ("pts", "valid_pts_min", "valid_pts_max"):
integer(getattr(self, name), name)
for name in ("utc_ns", "uncertainty_ns", "max_drift_ppm"):
integer(getattr(self, name), name, 0)
if not self.valid_pts_min <= self.pts <= self.valid_pts_max:
raise ValueError("anchor outside calibrated range")
class FrameClock:
def __init__(self, camera_id, source_id, stream_epoch, *, clock_jump_ns=50_000_000):
self.camera_id = integer(camera_id, "camera_id", 0)
self.source_id, self.stream_epoch = identifier(source_id), identifier(stream_epoch)
self.clock_jump_ns = integer(clock_jump_ns, "clock_jump_ns", 0)
self.last = None
self.clock_epoch = 0
def observe(self, *, source_seq, mono_before_ns, mono_after_ns, utc_ns,
sync_uncertainty_ns=None, raw_pts=None, raw_dts=None,
tb_num=None, tb_den=None, origin_id=None, anchor=None):
"""Called once at original frame acceptance, before sampling/queueing.
Bracket UTC read with monotonic reads. Unknown host synchronization error
stays None. Reuse the stamp with the exact pixels; never restamp a crop.
"""
source_seq = integer(source_seq, "source_seq", 1)
before = integer(mono_before_ns, "mono_before_ns", 0)
after = integer(mono_after_ns, "mono_after_ns", before)
utc_ns = integer(utc_ns, "utc_ns", 0)
mono = (before + after) // 2
if origin_id is not None:
identifier(origin_id)
uncertainty = None
if sync_uncertainty_ns is not None:
uncertainty = integer(sync_uncertainty_ns, "sync_uncertainty_ns", 0) + (after-before+1)//2
if (tb_num is None) != (tb_den is None):
raise ValueError("partial timebase")
if tb_num is not None:
timebase(tb_num, tb_den)
for name, v in (("raw_pts", raw_pts), ("raw_dts", raw_dts)):
if v is not None:
integer(v, name)
if tb_num is None:
raise ValueError("timestamp without timebase")
clock_epoch = self.clock_epoch
if self.last:
if source_seq <= self.last.source_seq or mono <= self.last.decode_mono_ns:
raise ValueError("duplicate/late sequence or monotonic clock")
jump = abs((utc_ns-self.last.decode_utc_ns)-(mono-self.last.decode_mono_ns))
if jump > self.clock_jump_ns:
clock_epoch += 1
capture, capture_uncertainty, anchor_id = None, None, None
if anchor is not None:
if (anchor.source_id, anchor.stream_epoch) != (self.source_id, self.stream_epoch):
raise ValueError("foreign capture anchor")
if raw_pts is not None and timebase(tb_num, tb_den) == timebase(anchor.tb_num, anchor.tb_den):
if anchor.valid_pts_min <= raw_pts <= anchor.valid_pts_max:
delta = (raw_pts-anchor.pts) * timebase(tb_num, tb_den) * NS
capture = anchor.utc_ns + round(delta)
# Round upward; never hide timestamp quantization or drift.
drift = abs(delta) * anchor.max_drift_ppm / 1_000_000
capture_uncertainty = anchor.uncertainty_ns + (drift.numerator+drift.denominator-1)//drift.denominator + 1
anchor_id = anchor.anchor_id
stamp = FrameStamp(self.camera_id, self.source_id, self.stream_epoch, source_seq,
origin_id, raw_pts, raw_dts, tb_num, tb_den, mono, utc_ns,
uncertainty, clock_epoch, capture, capture_uncertainty, anchor_id)
self.clock_epoch = clock_epoch
self.last = stamp
return stamp
def require_current(self, stamp, *, now_mono_ns, max_age_ns, owner, expected_owner):
if owner is None or expected_owner is None or owner != expected_owner:
raise ValueError("wrong owner")
if (stamp.camera_id, stamp.source_id, stamp.stream_epoch) != (self.camera_id, self.source_id, self.stream_epoch):
raise ValueError("wrong source/epoch")
age = integer(now_mono_ns, "now_mono_ns", 0) - stamp.decode_mono_ns
if not 0 <= age <= integer(max_age_ns, "max_age_ns", 0):
raise ValueError("late/future frame")
return stamp
@dataclass(frozen=True)
class RecorderMap:
"""Actual per-packet values observed around mux; never predicted from tail.
origin_id must be propagated by the same upstream producer to image and mux
paths. Independently generated decoder counters are not common identities.
"""
camera_id: int
recording_id: str
source_id: str
stream_epoch: str
origin_id: str
source_pts: int
source_dts: int | None
source_tb_num: int
source_tb_den: int
output_pts: int
output_dts: int
output_tb_num: int
output_tb_den: int
timeline_segment: int
def __post_init__(self):
integer(self.camera_id, "camera_id", 0)
for v in (self.recording_id, self.source_id, self.stream_epoch, self.origin_id):
identifier(v)
timebase(self.source_tb_num, self.source_tb_den)
timebase(self.output_tb_num, self.output_tb_den)
for name in ("source_pts", "output_pts", "output_dts", "timeline_segment"):
integer(getattr(self, name), name)
if self.source_dts is not None:
integer(self.source_dts, "source_dts")
integer(self.timeline_segment, "timeline_segment", 0)
class RecorderIndex:
def __init__(self, recording_id, source_id, stream_epoch, *, camera_id, capacity=4096):
self.camera_id = integer(camera_id, "camera_id", 0)
self.identity = tuple(identifier(x) for x in (recording_id, source_id, stream_epoch))
self.rows = deque(maxlen=integer(capacity, "capacity", 1))
self.evicted = 0
def append(self, row):
if row.camera_id != self.camera_id or (row.recording_id, row.source_id, row.stream_epoch) != self.identity:
raise ValueError("foreign recording source")
if self.rows:
last = self.rows[-1]
if row.output_dts*timebase(row.output_tb_num,row.output_tb_den) <= last.output_dts*timebase(last.output_tb_num,last.output_tb_den):
raise ValueError("mux DTS not strictly increasing")
if row.timeline_segment < last.timeline_segment:
raise ValueError("late timeline segment")
if len(self.rows) == self.rows.maxlen:
self.evicted += 1
self.rows.append(row)
def output_time(self, stamp):
if stamp.camera_id != self.camera_id or (stamp.source_id, stamp.stream_epoch) != self.identity[1:]:
raise ValueError("foreign frame source")
if stamp.origin_id is None or stamp.raw_pts is None:
raise ValueError("no shared upstream frame identity")
matches = [r for r in self.rows if r.origin_id == stamp.origin_id and
r.source_pts*timebase(r.source_tb_num,r.source_tb_den) == stamp.raw_pts*timebase(stamp.tb_num,stamp.tb_den)]
if len(matches) != 1:
raise ValueError("absent/ambiguous mapping; do not interpolate")
row = matches[0]
return Fraction(row.output_pts) * timebase(row.output_tb_num,row.output_tb_den)
class BoundedJournal:
"""Bounded memory only. A separate diagnostic consumer may serialize snapshot.
ponytail: one deque per stream; no disk writes or asynchronous logging worker
until an actual bound runtime integration and its latency budget are reviewed.
"""
def __init__(self, capacity=4096):
self.rows = deque(maxlen=integer(capacity, "capacity", 1))
self.evicted = 0
def append(self, row):
if type(row) not in (FrameStamp, RecorderMap):
raise ValueError("only validated metadata; no payload/log dictionaries")
if len(self.rows) == self.rows.maxlen:
self.evicted += 1
self.rows.append(row)
def snapshot_json(self):
return json.dumps({"evicted": self.evicted, "rows": [asdict(x) for x in self.rows]}, allow_nan=False, separators=(",", ":"))

@ -1,178 +0,0 @@
"""Explicit offline producer glue; use the existing camera control lock/worker.
No startup side effects, lifecycle grants, model loading, background threads or
physical I/O. bind_source/revoke must be wired into the REAL dispatcher before
deployment. Actual inference producer must preserve original FrameStamp pixels.
"""
import hashlib
import json
from .alarm_eligibility import AlarmEligibility, Context, Frame, Semantic
from .inspection_input import adapt_result
from .inspection_runtime import CropContext, CropWorker, check_stamp, source_key
from .unknown_inspection import Session, Settings
def source_token(key):
if type(key) is not tuple or len(key) != 3:
return None
return hashlib.sha256(json.dumps(key,separators=(',',':')).encode('ascii')).hexdigest()
class InspectionBridge:
def __init__(self, *, settings, cameras, proposal_contract, classifier_contract,
owner, control_lock, controller, alarm_ready, state_provider, clock, quality=None):
if not isinstance(settings, Settings):
raise ValueError('Calibrated settings required')
self.settings, self.proposal, self.classifier = settings, proposal_contract, classifier_contract
self.owner, self.control_lock, self.controller = owner, control_lock, controller
self.alarm_ready, self.state_provider, self.clock = alarm_ready, state_provider, clock
self.quality = quality
self.crops = CropWorker(tuple(cameras))
self.gate = AlarmEligibility(semantic_min=settings.semantic_min, margin=settings.semantic_margin,
min_side=settings.min_side_px, sharpness_min=settings.min_sharpness)
self.contexts = {}
# Validate both actual tasks/names/SHAs even before the first frame.
test = Context(tuple(cameras)[0], 1, (1,), 'validation_epoch', settings.proposal_sha, settings.classifier_sha)
self.gate.begin(test, proposal_contract=proposal_contract, classifier_contract=classifier_contract)
self.gate.revoke(test.camera)
def revoke(self, camera, st, reason):
"""Existing dispatcher still performs its own STOP/invalidation."""
if st is not self.state_provider(camera):
return False
self.crops.revoke(camera)
self.gate.revoke(camera)
self.contexts.pop(camera, None)
st['inspection_authorized'] = False
st['inspection_common_alarm_guard'] = None
if isinstance(st.get('inspection_session'), Session):
st['inspection_session'].phase = 'closed'
st['inspection_session'].revoke_semantics(reason)
def bind_source(self, camera, st, stamp):
"""Trusted lifecycle hook, under the existing control lock. No grant."""
if st is not self.state_provider(camera):
return False
if stamp.camera_id != camera:
raise ValueError('Foreign source')
key = source_key(stamp)
if st.get('inspection_source_binding') != key:
self.revoke(camera, st, 'source_or_clock_epoch_changed')
st['inspection_source_binding'] = key
st.pop('inspection_detector_stamp', None)
st.pop('inspection_semantic_stamp', None)
st.pop('inspection_input_mono', None)
st['inspection_control_deadline'] = 0.
def retire_closed(self, camera, st, *, inspection_id, expected_owner):
"""Explicit new discovery, never an automatic reconnect/time-out retry.
Caller holds the control lock and has issued a NEW owner token. Neither
authorization, inspection serial nor the global no-effect latch resets.
"""
session = st.get('inspection_session')
if (st is not self.state_provider(camera)
or st.get('inspection_authorized') is not False or not isinstance(session,Session)
or session.phase != 'closed' or session.inspection_id != inspection_id
or expected_owner != self.owner(st) or expected_owner == session.owner):
return False
self.revoke(camera,st,'explicit_new_discovery')
st['inspection_retired_summary'] = (session.inspection_id,session.deadline_mono,session.owner)
st.pop('inspection_session',None)
st.pop('inspection_detector_stamp',None)
st.pop('inspection_semantic_stamp',None)
st['inspection_control_deadline'] = 0.
return True
def _matching_context(self, camera, st):
ctx = self.contexts.get(camera)
session = st.get('inspection_session')
if (st is not self.state_provider(camera) or not ctx or not isinstance(session,Session)
or session.inspection_id != ctx.inspection_id or session.owner != ctx.owner
or session.contract != self.settings or self.owner(st) != ctx.owner
or source_token(st.get('inspection_source_binding')) != ctx.source_id
or ctx.proposal_sha != self.settings.proposal_sha
or ctx.classifier_sha != self.settings.classifier_sha):
return None
return ctx
def common_ready(self, camera, st):
ctx = self._matching_context(camera,st)
return bool(ctx and self.gate.eligible(ctx,self.clock()))
def active_context(self, camera):
"""Use as alarm_boundary.bind_guard provider: Session AND shared gate."""
st = self.state_provider(camera)
ctx = self._matching_context(camera,st)
return ctx if ctx and self.alarm_ready(st) else None
def process(self, camera, st, stamp, frame, result, *, acquired_owner, occluded=None, visual_sample=None, handoff_check=None):
"""Control first; copy the accepted recognition crop after releasing lock.
Occlusion False must come from validated quality evidence, not from a
classifier label or assumption. None keeps semantics unusable.
"""
pending = None
with self.control_lock(camera):
# Validate the original ticket epoch atomically with controller
# admission; the crop copy below still remains outside this lock.
if handoff_check is not None:
try:
if handoff_check() is not True:
return False
except Exception:
return False
if (st is not self.state_provider(camera)
or camera not in self.crops.cameras or not self.settings.enabled
or not check_stamp(stamp, camera=camera, seq=getattr(stamp,'source_seq',None),
owner=acquired_owner, expected_owner=self.owner(st),
binding=st.get('inspection_source_binding'), now=self.clock(), age=.65)):
# A foreign/late callback cannot revoke or STOP a new owner.
return False
ctx = self.contexts.get(camera)
session = st.get('inspection_session')
rec, rec_stamp = None, None
if ctx and isinstance(session,Session) and ctx.owner == self.owner(st) and ctx.inspection_id == session.inspection_id:
crop_ctx = CropContext(camera,ctx.inspection_id,ctx.owner,source_key(stamp),ctx.classifier_sha)
row = self.crops.take_stamped(crop_ctx, now=self.clock())
if row:
rec_stamp, rec = row
f = Frame(rec.source_seq,rec_stamp.decode_mono_ns/1e9,rec.bbox,rec.shape)
self.gate.submit(ctx, Semantic(f,rec.classifier_sha,rec.scores,rec.sharpness,
rec.clipped,rec.occluded), self.clock())
adapted = adapt_result(result,camera=camera,owner=acquired_owner,source_seq=stamp.source_seq,
observed_at=stamp.decode_utc_ns/1e9,frame_shape=frame.shape,
actual_model_sha=self.proposal.sha256,frame_stamp=stamp,
recognition=rec,recognition_stamp=rec_stamp)
self.controller(camera,frame,adapted,True,stamp.source_seq, visual_sample=visual_sample)
session = st.get('inspection_session')
if (not isinstance(session,Session) or session.phase != 'inspection'
or st.get('inspection_authorized') is not True or session.owner != self.owner(st)
or not session.live(self.clock())):
self.crops.revoke(camera); self.gate.revoke(camera); self.contexts.pop(camera,None)
return False
key = source_key(stamp)
ctx = Context(camera,session.inspection_id,self.owner(st),
source_token(key),
self.settings.proposal_sha,self.settings.classifier_sha)
if self.contexts.get(camera) != ctx:
self.gate.begin(ctx,proposal_contract=self.proposal,classifier_contract=self.classifier)
self.contexts[camera] = ctx
st['inspection_common_alarm_guard'] = lambda: self.common_ready(camera,st)
record = session.recent.get(stamp.source_seq)
if record != (stamp.decode_utc_ns/1e9,session.bbox,session.shape,self.owner(st)):
self.gate.revoke(camera); self.crops.revoke(camera); self.contexts.pop(camera,None)
return False
evidence = Frame(stamp.source_seq,stamp.decode_mono_ns/1e9,session.bbox,session.shape)
if not self.gate.observe(ctx,evidence,self.clock()):
return False
crop_ctx = CropContext(camera,session.inspection_id,self.owner(st),key,self.settings.classifier_sha)
self.crops.bind(crop_ctx)
pending = crop_ctx, session.bbox
if self.quality is not None:
try:
occluded = self.quality(camera, stamp, frame, pending[1])
except Exception:
occluded = None
return self.crops.submit(pending[0],stamp,frame,pending[1],now=self.clock(),occluded=occluded)

@ -1,268 +0,0 @@
"""Opt-in offline adapter; no model loader, thread, actuator or automatic grant.
The real decoder MUST call begin_source, then accepted immediately after each
successful decode, before queue/throttle/inference. Its newly allocated image
buffer must remain owned by that ticket and must never be reused or mutated.
Lock order: camera lifecycle barrier, then control RLock, then lens lock.
A transition callback must not newly acquire lifecycle locks under control.
"""
from dataclasses import dataclass
from types import SimpleNamespace
import time
from .frame_time import FrameClock
from .inspection_runtime import check_stamp
_configured = None
def enabled():
from . import config
return getattr(config, 'UNKNOWN_INSPECTION_ENABLE', False) is True
def configure(adapter):
global _configured
if not isinstance(adapter, Handoff):
raise ValueError('Explicit verified-model bridge required')
from . import alarm_boundary
alarm_boundary.bind_guard(adapter.bridge.gate, adapter.bridge.active_context)
_configured = adapter
def require_configured():
if not isinstance(_configured, Handoff):
raise RuntimeError('UNKNOWN producer/dispatcher/model binding is not configured')
return _configured
@dataclass(frozen=True)
class FrameTicket:
stamp: object
acquired_owner: tuple
state_ref: object
pixels: object
camera_epoch: int
handoff_epoch: int
class Handoff:
def __init__(self, bridge, *, camera_epoch, latest_visual,
mono_ns=time.monotonic_ns, utc_ns=time.time_ns, authorize=None):
self.bridge, self.camera_epoch, self.latest_visual = bridge, camera_epoch, latest_visual
self.mono_ns, self.utc_ns = mono_ns, utc_ns
self.sources, self.epochs = {}, {}
self.authorize = authorize
def begin_source(self, camera, source_id, stream_epoch, epoch):
with self.bridge.control_lock(camera):
st = self.bridge.state_provider(camera)
if epoch != self.camera_epoch(camera):
return False
previous = self.sources.get(camera)
key = source_id, stream_epoch, epoch, id(st)
if previous and previous[0] == key:
return True
clock = FrameClock(camera, source_id, stream_epoch)
self.bridge.revoke(camera, st, 'decoder_source_changed')
self.epochs[camera] = self.epochs.get(camera, 0)+1
self.sources[camera] = key, clock, st
self._clear_pending(st)
return True # NEVER grants inspection_authorized
def end_source(self, camera, stream_epoch=None, *, reason='decoder_disconnected'):
with self.bridge.control_lock(camera):
source = self.sources.get(camera)
if source is None or (stream_epoch is not None and source[0][1] != stream_epoch):
return
self.sources.pop(camera)
self.epochs[camera] += 1
st = self.bridge.state_provider(camera)
self._clear_pending(st)
self.bridge.revoke(camera, st, reason)
st.pop('inspection_source_binding', None)
st['inspection_control_deadline'] = 0.
@staticmethod
def _clear_pending(st):
for key in ('pending_frame', 'pending_source_seq', 'pending_inspection_ticket'):
st.pop(key, None)
def accepted(self, camera, frame, source_seq, epoch):
"""Call immediately after decode; preserve receipt/owner BEFORE lock wait.
This local receipt is not exposure time. A producer that already queued
its image must supply the original ticket, never call accepted again.
"""
original_state = self.bridge.state_provider(camera)
original_source = self.sources.get(camera)
if not original_source or original_source[2] is not original_state:
return None
original_owner = self.bridge.owner(original_state)
original_epoch = self.epochs.get(camera)
before = self.mono_ns(); utc = self.utc_ns(); after = self.mono_ns()
received = (before+after)//2
with self.bridge.control_lock(camera):
st = self.bridge.state_provider(camera)
source = self.sources.get(camera)
if (source is not original_source or st is not original_state
or original_epoch != self.epochs.get(camera)
or original_owner != self.bridge.owner(st)
or epoch != source[0][2] or epoch != self.camera_epoch(camera)
or not 0 <= (self.mono_ns()-received)/1e9 <= .65):
return None
try:
stamp = source[1].observe(source_seq=source_seq, mono_before_ns=before,
mono_after_ns=after, utc_ns=utc)
except ValueError: # another accepted newer image may have won the lock
return None
self.bridge.bind_source(camera, st, stamp)
return FrameTicket(stamp, original_owner, st, frame, epoch, original_epoch)
def current(self, ticket, *, age=.65):
if not isinstance(ticket, FrameTicket):
return False
camera = ticket.stamp.camera_id
st = self.bridge.state_provider(camera)
return bool(ticket.state_ref is st
and ticket.handoff_epoch == self.epochs.get(camera)
and ticket.camera_epoch == self.camera_epoch(camera)
and check_stamp(ticket.stamp, camera=camera, seq=ticket.stamp.source_seq,
owner=ticket.acquired_owner, expected_owner=self.bridge.owner(st),
binding=st.get('inspection_source_binding'), now=self.mono_ns()/1e9, age=age))
def note_age(self, ticket, stage):
if self.current(ticket):
ticket.state_ref.setdefault('inspection_decode_age_s', {})[stage] = max(
0., (self.mono_ns()-ticket.stamp.decode_mono_ns)/1e9)
def bind_item(self, item, ticket):
cam, frame, _ptz, seq, future, _queued = item
if (not self.current(ticket) or ticket.stamp.camera_id != cam
or frame is not ticket.pixels or seq != ticket.stamp.source_seq):
return False
future.inspection_ticket = ticket
future.visual_sample = None
self.note_age(ticket, 'enqueue')
return True
def pending(self, ticket):
if not isinstance(ticket, FrameTicket):
return False
camera = ticket.stamp.camera_id
with self.bridge.control_lock(camera):
if not self.current(ticket):
return False
st = ticket.state_ref
current = st.get('pending_inspection_ticket')
if current and ticket.stamp.source_seq <= current.stamp.source_seq:
return False
st['pending_frame'], st['pending_source_seq'], st['pending_inspection_ticket'] = (
ticket.pixels, ticket.stamp.source_seq, ticket)
return True
def refresh(self, item):
camera, _frame, _ptz, seq, future, queued = item
with self.bridge.control_lock(camera):
st = self.bridge.state_provider(camera)
pending = st.get('pending_inspection_ticket')
if pending is None:
return item, False
if (not self.current(pending) or st.get('pending_frame') is not pending.pixels
or st.get('pending_source_seq') != pending.stamp.source_seq):
self._clear_pending(st)
return item, False
if pending.stamp.source_seq <= seq:
return item, False
self._clear_pending(st)
updated = camera, pending.pixels, _ptz, pending.stamp.source_seq, future, queued
self.bind_item(updated, pending) # replaces the whole ticket, never a timestamp
self.note_age(pending, 'pending_refresh')
return updated, True
def prepare(self, item):
camera, _frame, ptz, _seq, future, queued = item
with self.bridge.control_lock(camera):
ticket = getattr(future, 'inspection_ticket', None)
if (not self.current(ticket) or ticket.stamp.camera_id != camera
or ticket.pixels is not _frame or ticket.stamp.source_seq != _seq):
return item
saved = self.latest_visual(camera, self.utc_ns()/1e9)
if saved is None:
return item
pixels, sample = saved
paired = getattr(sample, 'inspection_ticket', None)
if (not self.current(paired, age=.20) or pixels is not paired.pixels
or sample.source_seq != paired.stamp.source_seq
or sample.owner != paired.acquired_owner
or getattr(sample, 'inspection_stamp', None) != paired.stamp
or sample.result.source_seq != paired.stamp.source_seq):
return item
future.inspection_ticket, future.visual_sample = paired, sample
self.note_age(paired, 'paired_before_inference')
return camera, pixels, ptz, paired.stamp.source_seq, future, queued
def prune(self, items):
valid = []
for item in items:
camera, frame, _ptz, seq, future, _ = item
ticket = getattr(future, 'inspection_ticket', None)
if (self.current(ticket) and ticket.pixels is frame
and ticket.stamp.camera_id == camera and ticket.stamp.source_seq == seq):
self.note_age(ticket, 'before_inference')
valid.append(item)
elif not future.done():
future.set_result(None)
return valid
def process_item(self, camera, pixels, result, ptz, seq, future):
ticket = getattr(future, 'inspection_ticket', None)
if (not ptz or not self.current(ticket) or ticket.pixels is not pixels
or ticket.stamp.camera_id != camera or ticket.stamp.source_seq != seq):
return False
self.note_age(ticket, 'after_inference')
return self.bridge.process(camera, ticket.state_ref, ticket.stamp, pixels, result,
acquired_owner=ticket.acquired_owner, visual_sample=getattr(future,'visual_sample',None),
handoff_check=lambda: self._authorize_current(ticket))
def _authorize_current(self, ticket):
if not self.current(ticket):
return False
if self.authorize is None:
return True # Explicit external grant used by an embedded dispatcher.
st = ticket.state_ref
try:
allowed = self.authorize(ticket.stamp.camera_id, ticket.acquired_owner) is True
except Exception:
allowed = False
if not self.current(ticket):
return False
if not allowed and st.get('inspection_authorized') is True:
self.bridge.revoke(ticket.stamp.camera_id, st, 'inspection_authorization_revoked')
st['inspection_authorized'] = allowed
return True # The controller handles STOP for denied active sessions.
def visual_sample(self, ticket, result):
if not self.current(ticket, age=.25) or result.source_seq != ticket.stamp.source_seq:
return None
return SimpleNamespace(owner=ticket.acquired_owner, source_seq=ticket.stamp.source_seq,
captured_at=ticket.stamp.decode_utc_ns/1e9, result=result,
inspection_stamp=ticket.stamp, inspection_owner=ticket.acquired_owner,
inspection_ticket=ticket)
def transition(self, camera, st, acquired_owner, reason, existing_transition):
"""Explicit FULLSTOP/manual/source retirement; callback keeps physical STOP.
Never wrap arbitrary short geometry/watchdog STOP as a lifecycle revoke.
Enter any camera lifecycle barrier BEFORE this API; multiple IDs use
its existing ascending-ID order. The callback must never acquire a new
lifecycle lock under this control RLock. Lens locks come last.
"""
with self.bridge.control_lock(camera):
if st is not self.bridge.state_provider(camera) or acquired_owner != self.bridge.owner(st):
return False
self.epochs[camera] = self.epochs.get(camera, 0)+1
self._clear_pending(st)
self.bridge.revoke(camera, st, reason)
existing_transition() # no grant, budget/no-effect reset, or new PTZ worker
return True

@ -1,64 +0,0 @@
"""Explicit detector-result adapter; never invent a fresh acquisition timestamp.
Call at the inference producer with the frame's original local decode time and
owner token. Actual model hash must come from the validated loaded-model contract.
The producer must not pass time.time() after inference as observed_at.
"""
from .unknown_inspection import Observation
from .frame_time import FrameStamp
class InspectionVisual:
def __init__(self, original, stamp, owner):
if (not isinstance(stamp,FrameStamp) or original.source_seq != stamp.source_seq
or original.captured_at != stamp.decode_utc_ns/1e9 or original.owner != owner):
raise ValueError('Exact original visual sample stamp/owner required')
self.original, self.inspection_stamp, self.inspection_owner = original,stamp,owner
def __getattr__(self,name):
return getattr(self.original,name)
class InspectionResult:
def __init__(self, original, observation, recognition, stamp, owner, recognition_stamp):
self.original = original
self.inspection_observation = observation
self.inspection_recognition = recognition
self.inspection_stamp = stamp
self.inspection_owner = owner
self.inspection_recognition_stamp = recognition_stamp
def __getattr__(self, name):
return getattr(self.original, name)
def adapt_result(result, *, camera, owner, source_seq, observed_at,
frame_shape, actual_model_sha, frame_stamp, recognition=None, recognition_stamp=None):
if (not isinstance(frame_stamp, FrameStamp) or frame_stamp.camera_id != camera
or frame_stamp.source_seq != source_seq or owner is None
or frame_stamp.decode_utc_ns/1e9 != observed_at):
raise ValueError('Exact original producer stamp required')
if recognition is not None and (not isinstance(recognition_stamp, FrameStamp)
or recognition_stamp.camera_id != camera
or recognition_stamp.source_seq != recognition.source_seq
or recognition_stamp.decode_utc_ns/1e9 != recognition.observed_at
or recognition.owner != owner):
raise ValueError('Original recognition frame stamp required')
names = getattr(result, 'names', {})
if names != {0: 'airborne_object'}:
raise ValueError('A generic model contract is required; old class 0 is not generic')
boxes = result.boxes
if boxes is None:
detections = ()
else:
xyxy = boxes.xyxy.detach().cpu().tolist()
scores = boxes.conf.detach().cpu().tolist()
classes = boxes.cls.detach().cpu().tolist()
if not len(xyxy) == len(scores) == len(classes) or len(xyxy) > 64:
raise ValueError('Invalid or excessive proposals')
if any(c != int(c) for c in classes):
raise ValueError('Non-integral proposal class')
detections = tuple((tuple(b), c, int(k)) for b, c, k in zip(xyxy, scores, classes))
obs = Observation(camera, owner, source_seq, observed_at, actual_model_sha,
('airborne_object',), tuple(frame_shape[:2]), detections)
return InspectionResult(result, obs, recognition, frame_stamp, owner, recognition_stamp)

@ -1,240 +0,0 @@
"""Offline integration candidate. No network, model loader, threads or PTZ worker.
The producer binds source/epoch under the existing camera control lock. The
classifier calls run_one on its OWN worker, never on the camera control thread.
Unknown occlusion quality is not evidence that an object is unobscured.
"""
from collections import OrderedDict
from dataclasses import dataclass
from math import ceil, floor
from itertools import islice
from threading import Lock
from .frame_time import FrameStamp
from .unknown_inspection import Recognition, finite, valid_box
def source_key(stamp):
return stamp.source_id, stamp.stream_epoch, stamp.clock_epoch
def check_stamp(stamp, *, camera, seq, owner, expected_owner, binding, now, age):
return (isinstance(stamp, FrameStamp) and stamp.camera_id == camera
and type(seq) is int and stamp.source_seq == seq and seq > 0
and owner is not None and owner == expected_owner
and binding == source_key(stamp) and finite(now, age)
and 0 <= now-stamp.decode_mono_ns/1e9 <= age)
def provenance(st, result, sample, *, camera, seq, owner, mono, visual_only):
"""Only accepted producer stamps can tighten the controller's deadline.
Called after foreign-owner early return, under the existing control lock.
Binding MUST be set by source lifecycle; it is never learned from a result.
"""
value = sample if visual_only else result
stamp = getattr(value, 'inspection_stamp', None)
incoming_owner = getattr(value, 'inspection_owner', None)
if not check_stamp(stamp, camera=camera, seq=seq, owner=incoming_owner,
expected_owner=owner, binding=st.get('inspection_source_binding'),
now=mono, age=.25 if visual_only else .65):
return 'missing_or_stale_original_stamp'
acquired = stamp.decode_mono_ns/1e9
if not visual_only:
last = st.get('inspection_detector_stamp')
if (last is not None and (source_key(last) != source_key(stamp)
or stamp.source_seq <= last.source_seq
or stamp.decode_mono_ns <= last.decode_mono_ns)):
return 'duplicate_or_reordered_original_frame'
st['inspection_detector_stamp'] = stamp
st['inspection_input_mono'] = acquired
return ''
def current_detector(st, mono):
stamp = st.get('inspection_detector_stamp')
return bool(isinstance(stamp, FrameStamp)
and source_key(stamp) == st.get('inspection_source_binding')
and finite(mono) and 0 <= mono-stamp.decode_mono_ns/1e9 <= .65)
@dataclass(frozen=True)
class CropContext:
camera: int
inspection_id: int
owner: tuple
source: tuple
classifier_sha: str
@dataclass(frozen=True)
class CropJob:
context: CropContext
stamp: FrameStamp
bbox: tuple
shape: tuple
pixels: object
sharpness: float
clipped: bool
occluded: bool | None
class CropWorker:
"""One in-flight callback, one pending crop/result per configured camera.
Replacement keeps camera FIFO position: a busy camera cannot starve others.
max_pixels bounds each copied crop; full frames are never retained. A stalled
classifier can delay recognition, but submit/take do not acquire its lock.
"""
def __init__(self, cameras, *, max_pixels=1024*1024):
if (type(cameras) not in (tuple, list) or not cameras or len(cameras) > 6
or any(type(c) is not int or c < 0 for c in cameras)
or len(set(cameras)) != len(cameras)
or type(max_pixels) is not int or not 1 <= max_pixels <= 1024*1024):
raise ValueError('Bounded physical camera set required')
self.cameras, self.max_pixels = frozenset(cameras), max_pixels
self._pending, self._results, self._active = OrderedDict(), {}, {}
self._latest = {}
self._decode_ages = {} # bounded by the configured camera set
self._generation = {c: 0 for c in self.cameras}
self._lock, self._worker = Lock(), Lock()
def bind(self, context):
from .unknown_inspection import digest
if (not isinstance(context, CropContext) or context.camera not in self.cameras
or type(context.inspection_id) is not int or context.inspection_id <= 0
or not context.owner or type(context.source) is not tuple or len(context.source) != 3
or not digest(context.classifier_sha)):
raise ValueError('Explicit inspection/source/model context required')
with self._lock:
if self._active.get(context.camera) == context:
return
self._generation[context.camera] += 1
self._active[context.camera] = context
self._pending.pop(context.camera, None)
self._results.pop(context.camera, None)
self._latest.pop(context.camera, None)
self._decode_ages.pop(context.camera, None)
def revoke(self, camera):
if camera not in self.cameras:
raise ValueError('Unknown physical camera')
with self._lock:
self._generation[camera] += 1
self._active.pop(camera, None)
self._pending.pop(camera, None)
self._results.pop(camera, None)
self._latest.pop(camera, None)
self._decode_ages.pop(camera, None)
def submit(self, context, stamp, frame, bbox, *, now, occluded=None):
import numpy as np
if (not isinstance(context, CropContext) or context.camera not in self.cameras
or not isinstance(frame, np.ndarray) or frame.dtype != np.uint8
or frame.ndim != 3 or frame.shape[2] != 3
or not valid_box(bbox, tuple(frame.shape[:2]))
or occluded is not None and type(occluded) is not bool
or not check_stamp(stamp, camera=context.camera, seq=getattr(stamp, 'source_seq', None),
owner=context.owner, expected_owner=context.owner,
binding=context.source, now=now, age=.65)):
return False
with self._lock:
if self._active.get(context.camera) != context:
return False
generation = self._generation[context.camera]
x1, y1, x2, y2 = bbox
left, top, right, bottom = floor(x1), floor(y1), ceil(x2), ceil(y2)
if (right-left)*(bottom-top) > self.max_pixels:
return False
# Copy belongs to this exact image and sequence; do not resize/upscale it
# to meet recognition thresholds or invent source detail.
pixels = frame[top:bottom, left:right].copy()
if pixels.shape[0] < 3 or pixels.shape[1] < 3:
return False
gray = pixels.astype(np.float32).mean(axis=2)
lap = -4*gray[1:-1, 1:-1]+gray[:-2, 1:-1]+gray[2:, 1:-1]+gray[1:-1, :-2]+gray[1:-1, 2:]
sharpness = float(lap.var())
pixels.flags.writeable = False
job = CropJob(context, stamp, tuple(bbox), tuple(frame.shape[:2]), pixels,
sharpness, x1 <= 0 or y1 <= 0 or x2 >= frame.shape[1] or y2 >= frame.shape[0], occluded)
with self._lock:
if (self._active.get(context.camera) != context
or self._generation[context.camera] != generation):
return False
last = self._latest.get(context.camera)
if last and (stamp.source_seq <= last.source_seq or stamp.decode_mono_ns <= last.decode_mono_ns):
return False
self._latest[context.camera] = stamp
self._pending[context.camera] = job
return True
def run_one(self, classify, *, clock):
"""Return False when busy/empty; failures leave the object UNKNOWN."""
if not self._worker.acquire(blocking=False):
return False
try:
with self._lock:
if not self._pending:
return False
camera, job = self._pending.popitem(last=False)
generation = self._generation[camera]
start_age = clock()-job.stamp.decode_mono_ns/1e9
with self._lock:
if self._active.get(camera) == job.context and self._generation[camera] == generation:
self._decode_ages[camera] = {'recognition_start': start_age}
if not 0 <= start_age <= .65:
return False
try:
scores = tuple(islice(classify(job.pixels), 5))
from .unknown_inspection import TARGETS, NON_TARGETS
if (len(scores) != 4 or any(type(p) is not tuple or len(p) != 2
or type(p[0]) is not str or not finite(p[1]) or not 0 <= p[1] <= 1 for p in scores)
or {p[0] for p in scores} != TARGETS | NON_TARGETS
or abs(sum(p[1] for p in scores)-1) > 1e-4):
return False
except Exception:
return False
# The callback cannot bless clipping, missing occlusion quality,
# completion time, source or owner. It returns semantic scores only.
rec = Recognition(camera, job.context.inspection_id, job.context.owner,
job.stamp.source_seq, job.stamp.decode_utc_ns/1e9,
job.context.classifier_sha, job.bbox, job.shape, scores,
job.sharpness, job.clipped, job.occluded is not False)
with self._lock:
if (self._active.get(camera) != job.context
or self._generation[camera] != generation):
return False
complete_age = clock()-job.stamp.decode_mono_ns/1e9
self._decode_ages[camera]['recognition_complete'] = complete_age
if not 0 <= complete_age <= .65:
return False
self._results[camera] = (job.context, job.stamp, rec)
return True
finally:
self._worker.release()
def take(self, context, *, now):
row = self.take_stamped(context, now=now)
return row[1] if row else None
def take_stamped(self, context, *, now):
"""Exact original stamp accompanies a delayed classifier result."""
with self._lock:
if self._active.get(context.camera) != context:
return None
row = self._results.get(context.camera)
if not row or row[0] != context:
return None
self._results.pop(context.camera)
if not 0 <= now-row[1].decode_mono_ns/1e9 <= .65:
return None
return row[1], row[2]
def counts(self):
with self._lock:
return len(self._pending), len(self._results)
def decode_ages(self):
"""Latest bounded local decode ages, never camera exposure/capture lag."""
with self._lock:
return {camera: dict(row) for camera, row in self._decode_ages.items()}

@ -1,84 +0,0 @@
"""Opt-in server entry point for UNKNOWN using locally pinned PyTorch weights."""
import asyncio
import hashlib
from pathlib import Path
import time
from . import config, state, visual_control
from .inspection_bridge import InspectionBridge
from .inspection_handoff import Handoff, configure
from .model_class_contract import normalize_names, validate_contract
from .unknown_inspection import Settings
def _file_sha(path):
with path.open('rb') as file:
return hashlib.file_digest(file, 'sha256').hexdigest()
def _load_model(yolo, path, expected, role):
path = Path(path)
if not path.is_absolute() or path.suffix.lower() != '.pt' or not path.is_file():
raise ValueError(f'{role} requires an absolute local .pt checkpoint')
digest = _file_sha(path)
if digest != expected:
raise ValueError(f'{role} checkpoint SHA mismatch')
model = yolo(str(path)) # Read task from the checkpoint, never force it.
if _file_sha(path) != digest:
raise ValueError(f'{role} checkpoint changed while loading')
return model, validate_contract(path, digest, expected, model.names, role=role,
metadata_source='loaded_model.names', actual_task=model.task)
class ServerInspection(Handoff):
def __init__(self, bridge, detector, classifier, *, authorize):
super().__init__(bridge, camera_epoch=lambda camera: id(config.CAMERA_CONFIG.get(camera)),
latest_visual=visual_control.latest, authorize=authorize)
self.detector = detector
self.classifier = classifier
def detect(self, frames):
return self.detector(frames, verbose=False, conf=self.bridge.settings.proposal_min,
imgsz=int(config.INFER_IMGSZ), max_det=64)
def classify(self, crop):
result, = self.classifier(crop, verbose=False)
names = normalize_names(result.names)
if names != self.bridge.classifier.names:
raise ValueError('Classifier output labels differ from the loaded checkpoint')
scores = result.probs.data.detach().cpu().tolist()
if len(scores) != len(names):
raise ValueError('Classifier output count differs from the loaded checkpoint')
return tuple(zip(names, scores))
async def recognition_loop(self):
while True:
if not await asyncio.to_thread(self.bridge.crops.run_one, self.classify, clock=time.monotonic):
await asyncio.sleep(.01)
def configure_runtime():
from ultralytics import YOLO
from .postprocess import _inspection_alarm_ready, postprocess_control
settings = getattr(config, 'UNKNOWN_INSPECTION_SETTINGS', None)
cameras = tuple(getattr(config, 'UNKNOWN_INSPECTION_CAMERAS', ()))
authorize = getattr(config, 'UNKNOWN_INSPECTION_AUTHORIZE', None)
quality = getattr(config, 'UNKNOWN_INSPECTION_OCCLUDED', None)
if (not isinstance(settings, Settings) or not settings.enabled or not visual_control.enabled()
or not cameras or len(set(cameras)) != len(cameras)
or not set(cameras) <= set(config.PTZ_CAM_IDS)
or not callable(authorize) or not callable(quality)):
raise RuntimeError('UNKNOWN requires calibrated settings, PTZ allowlist, authorization and quality providers')
detector, proposal = _load_model(YOLO, config.UNKNOWN_INSPECTION_PROPOSAL_PATH,
settings.proposal_sha, 'generic_detector')
classifier, semantics = _load_model(YOLO, config.UNKNOWN_INSPECTION_CLASSIFIER_PATH,
settings.classifier_sha, 'semantic_classifier')
bridge = InspectionBridge(settings=settings, cameras=cameras, proposal_contract=proposal,
classifier_contract=semantics, owner=visual_control.owner, control_lock=visual_control.control_lock,
controller=postprocess_control, alarm_ready=_inspection_alarm_ready,
state_provider=lambda camera: state.ptz_states.get(camera, {}), clock=time.monotonic,
quality=quality)
handoff = ServerInspection(bridge, detector, classifier, authorize=authorize)
configure(handoff)
return handoff

@ -1,77 +0,0 @@
"""Pure metadata validation; this module does not load/deserialize model files."""
import ast
from dataclasses import dataclass
from pathlib import PurePath
from .alarm_eligibility import NAMES, sha
@dataclass(frozen=True)
class ModelContract:
sha256: str
suffix: str
names: tuple
role: str
metadata_source: str
task: str = ''
def normalize_names(raw):
if isinstance(raw, str):
if len(raw) > 4096:
raise ValueError('Excessive names metadata')
try:
tree = ast.parse(raw, mode='eval')
if isinstance(tree.body, ast.Dict):
keys = [ast.literal_eval(k) for k in tree.body.keys]
if len(set(keys)) != len(keys):
raise ValueError('Duplicate literal class IDs')
raw = ast.literal_eval(tree)
except (ValueError, SyntaxError, MemoryError, RecursionError) as exc:
raise ValueError('Invalid literal names metadata') from exc
if type(raw) in (list, tuple):
pairs = list(enumerate(raw))
elif type(raw) is dict:
pairs = []
for key, value in raw.items():
if type(key) is int:
index = key
elif type(key) is str and key.isdecimal() and str(int(key)) == key:
index = int(key)
else:
raise ValueError('Ambiguous class ID')
pairs.append((index, value))
else:
raise ValueError('Missing names metadata')
ids = [i for i, _ in pairs]
if (not pairs or len(set(ids)) != len(ids) or set(ids) != set(range(len(ids)))
or any(type(v) is not str or not v.strip() or v != v.strip() for _, v in pairs)):
raise ValueError('Non-contiguous/duplicate IDs or invalid labels')
names = tuple(v for _, v in sorted(pairs))
if len(set(names)) != len(names):
raise ValueError('Duplicate class labels')
return names
def validate_contract(path, actual_sha, expected_sha, raw_names, *, role, metadata_source, actual_task=None):
suffix = PurePath(path).suffix.lower()
supported = {'.pt': {'loaded_model.names', 'result.names'},
'.pth': {'loaded_model.names', 'result.names'},
'.onnx': {'onnx.metadata.names', 'result.names'},
'.engine': {'result.names'}}
if suffix not in supported or metadata_source not in supported[suffix]:
raise ValueError('Unsupported format or unverified metadata source')
if not sha(actual_sha) or actual_sha != expected_sha:
raise ValueError('Loaded artifact hash is not pinned')
expected_task = 'classify' if role == 'semantic_classifier' else 'detect'
if actual_task != expected_task:
raise ValueError('Model task must be independently verified, not inferred from class names')
names = normalize_names(raw_names)
if role == 'generic_detector' and names != ('airborne_object',):
raise ValueError('Generic detector must expose airborne_object only')
elif role == 'semantic_classifier' and set(names) != NAMES:
raise ValueError('Classifier must expose exactly the four reviewed semantic labels')
elif role not in ('generic_detector', 'semantic_classifier', 'legacy_display'):
raise ValueError('Unsupported model role')
# legacy_display preserves Fighter/drone numeric names; never upgrades their
# meaning to fixedwing_uav or to permission for unknown-object alarms.
return ModelContract(actual_sha, suffix, names, role, metadata_source, actual_task)

@ -1,265 +0,0 @@
"""Bounded unknown-object inspection policy. No model, network or actuator imports.
Scores and budgets are mandatory, calibrated inputs, not deployment defaults.
All timestamps called observed_at are local decoded-image times, not exposure UTC.
"""
from __future__ import annotations
from collections import OrderedDict
from dataclasses import dataclass, field
import math
import threading
TARGETS = frozenset({'multirotor_uav', 'fixed_wing_uav'})
NON_TARGETS = frozenset({'bird', 'manned_aircraft'})
def finite(*values):
return all(isinstance(v, (float, int)) and not isinstance(v, bool)
and math.isfinite(v) for v in values)
def digest(value):
return isinstance(value, str) and len(value) == 64 and set(value) <= set('0123456789abcdef')
def valid_box(box, shape):
return (len(box) == 4 and len(shape) == 2 and finite(*box, *shape)
and 0 <= box[0] < box[2] <= shape[1]
and 0 <= box[1] < box[3] <= shape[0])
def same_object(a, b, shape):
"""Tight spatial continuity, independent of semantic label."""
if not valid_box(a, shape) or not valid_box(b, shape):
return False
area_a = (a[2]-a[0]) * (a[3]-a[1])
area_b = (b[2]-b[0]) * (b[3]-b[1])
jump = max(abs(a[0]+a[2]-b[0]-b[2]) / (2*shape[1]),
abs(a[1]+a[3]-b[1]-b[3]) / (2*shape[0]))
return .3 <= area_a/area_b <= 3.33 and jump <= .035
@dataclass(frozen=True)
class Settings:
proposal_sha: str
classifier_sha: str
proposal_names: tuple
proposal_min: float
semantic_min: float
semantic_margin: float
min_side_px: int
min_sharpness: float
budget_sec: float
admission_frames: int = 3
semantic_frames: int = 2
enabled: bool = False
def __post_init__(self):
if not (digest(self.proposal_sha) and digest(self.classifier_sha)
and self.proposal_names == ('airborne_object',)
and finite(self.proposal_min, self.semantic_min, self.semantic_margin,
self.min_sharpness, self.budget_sec)
and .25 <= self.proposal_min <= 1
and 0 < self.semantic_min <= 1 and 0 < self.semantic_margin <= 1
and type(self.min_side_px) is int and self.min_side_px >= 2
and self.min_sharpness > 0 and 0 < self.budget_sec <= 120
and type(self.admission_frames) is int and self.admission_frames >= 2
and type(self.semantic_frames) is int and self.semantic_frames >= 2
and isinstance(self.enabled, bool)):
raise ValueError('Invalid or uncalibrated inspection contract')
@dataclass(frozen=True)
class Observation:
camera: int
owner: tuple
source_seq: int
observed_at: float
proposal_sha: str
proposal_names: tuple
shape: tuple
# bbox, RAW coarse confidence, coarse class ID. Never motion-boosted scores.
detections: tuple
@dataclass(frozen=True)
class Recognition:
camera: int
inspection_id: int
owner: tuple
source_seq: int
observed_at: float
classifier_sha: str
bbox: tuple
shape: tuple
scores: tuple # (semantic name, score), unique names
sharpness: float
clipped: bool = False
occluded: bool = False
@dataclass
class Session:
camera: int
inspection_id: int
owner: tuple
started_mono: float
deadline_mono: float
phase: str = 'candidate'
decision: str = 'unresolved'
reason: str = 'confirming_object'
bbox: tuple | None = None
shape: tuple = ()
last_seq: int = 0
last_at: float = 0.
proposal_votes: int = 0
semantic_seq: int = 0
semantic_at: float = 0.
semantic_name: str = ''
semantic_score: float = 0.
semantic_votes: int = 0
recent: dict = field(default_factory=dict)
contract: Settings | None = None
def revoke_semantics(self, reason):
self.semantic_votes = 0
self.semantic_score = 0.
self.semantic_name = ''
self.semantic_at = 0.
self.decision = 'unresolved'
self.reason = reason
def live(self, mono):
# A confirmed target hands over to ordinary tracking. The inspection
# deadline itself never changes. Lost semantic freshness revokes this
# permission before observe/control; it cannot renew an unknown budget.
return (finite(mono) and self.phase != 'closed' and self.started_mono <= mono
and (mono < self.deadline_mono or self.decision == 'target'))
def observe(self, o, settings, now, mono):
if self.phase == 'closed':
return False
if self.decision == 'target' and not 0 <= now-self.semantic_at <= .65:
self.revoke_semantics('semantic_evidence_expired')
if self.contract is None:
self.contract = settings
elif self.contract != settings:
self.phase = 'closed'
self.revoke_semantics('model_contract_changed')
return False
if not self.live(mono):
self.phase = 'closed'
self.revoke_semantics('inspection_timeout')
return False
if (o.camera != self.camera or o.owner != self.owner
or o.proposal_sha != settings.proposal_sha
or o.proposal_names != settings.proposal_names
or not isinstance(o.source_seq, int) or o.source_seq <= self.last_seq
or not finite(now, o.observed_at) or not 0 <= now-o.observed_at <= .65
or (self.last_at and o.observed_at <= self.last_at)):
self.revoke_semantics('invalid_observation')
return False
candidates = [(tuple(b), float(c)) for b, c, cls in o.detections
if cls == 0 and finite(c) and settings.proposal_min <= c <= 1
and valid_box(b, o.shape)]
if self.bbox is not None:
candidates = [(b, c) for b, c in candidates
if o.shape == self.shape and same_object(self.bbox, b, o.shape)]
if not candidates:
self.proposal_votes = 0
self.revoke_semantics('no_current_same_object')
return False
bbox, _ = max(candidates, key=lambda x: x[1])
if self.last_at and o.observed_at-self.last_at > .65:
self.proposal_votes = 0
self.revoke_semantics('evidence_gap')
self.bbox, self.shape = bbox, o.shape
self.last_at, self.last_seq = o.observed_at, o.source_seq
self.proposal_votes += 1
self.recent[o.source_seq] = (o.observed_at, bbox, o.shape, o.owner)
self.recent = {k: v for k, v in self.recent.items() if 0 <= now-v[0] <= .65}
while len(self.recent) > 16:
del self.recent[min(self.recent)]
if self.proposal_votes >= settings.admission_frames:
self.phase = 'inspection'
self.reason = 'fresh_object_no_class_required'
return self.proposal_votes >= settings.admission_frames
def recognize(self, r, settings, now, mono):
record = self.recent.get(r.source_seq)
if (not self.live(mono) or self.phase != 'inspection'
or r.camera != self.camera or r.inspection_id != self.inspection_id
or r.owner != self.owner or r.classifier_sha != settings.classifier_sha
or not finite(now, r.observed_at, r.sharpness)
or not 0 <= now-r.observed_at <= .65 or record is None
or record != (r.observed_at, r.bbox, r.shape, r.owner)):
return False
if r.source_seq <= self.semantic_seq:
return False # duplicate/delayed answers cannot supply new votes
self.semantic_seq = r.source_seq
formatted = (type(r.scores) is tuple and len(r.scores) == 4
and all(type(p) is tuple and len(p) == 2 and type(p[0]) is str for p in r.scores))
names = [n for n, _ in r.scores] if formatted else []
good = (formatted and len(names) == len(set(names)) and set(names) == TARGETS | NON_TARGETS
and all(finite(v) and 0 <= v <= 1 for _, v in r.scores)
and abs(sum(v for _, v in r.scores)-1) <= 1e-4
and r.clipped is False and r.occluded is False and valid_box(r.bbox, r.shape)
and min(r.bbox[2]-r.bbox[0], r.bbox[3]-r.bbox[1]) >= settings.min_side_px
and r.sharpness >= settings.min_sharpness)
ranked = sorted(r.scores, key=lambda x: x[1], reverse=True) if good else []
if (not good or ranked[0][1] < settings.semantic_min
or ranked[0][1]-ranked[1][1] < settings.semantic_margin):
self.revoke_semantics('insufficient_recognition')
return False
name, score = ranked[0]
same = name == self.semantic_name and 0 < r.observed_at-self.semantic_at <= .65
self.semantic_votes = self.semantic_votes+1 if same else 1
self.semantic_name, self.semantic_score, self.semantic_at = name, score, r.observed_at
self.decision = ('target' if name in TARGETS else 'non_target') \
if self.semantic_votes >= settings.semantic_frames else 'unresolved'
self.reason = 'confirmed_'+self.decision
return self.decision != 'unresolved'
def alarm_allowed(self, now, mono, owner, bbox, shape):
return bool(self.live(mono) and self.phase == 'inspection'
and owner == self.owner and self.decision == 'target'
and self.semantic_name in TARGETS and finite(now)
and 0 <= now-self.semantic_at <= .65
and 0 <= now-self.last_at <= .65
and shape == self.shape and same_object(self.bbox, bbox, shape))
class LatestRecognition:
"""Bounded fair mailbox: one pending/result per camera, no frame FIFO.
An external model worker takes tickets; control never waits for prediction.
It stores metadata only. The producer owns the actual bounded crop buffer.
"""
def __init__(self, cameras):
self.cameras = frozenset(cameras)
self.pending, self.results = OrderedDict(), {}
self.lock = threading.Lock()
def submit(self, camera, ticket):
if camera not in self.cameras:
raise ValueError('Unknown physical camera')
with self.lock:
self.pending[camera] = ticket # replacement preserves fairness order
def take(self):
with self.lock:
return self.pending.popitem(last=False) if self.pending else None
def complete(self, result):
if not isinstance(result, Recognition) or result.camera not in self.cameras:
raise ValueError('Invalid recognition result')
with self.lock:
old = self.results.get(result.camera)
if old is None or (result.inspection_id, result.source_seq) > (old.inspection_id, old.source_seq):
self.results[result.camera] = result
def poll(self, camera):
with self.lock:
return self.results.pop(camera, None)

@ -1,211 +0,0 @@
"""New V2 crop/provenance checks. Synthetic pixels, no models or network."""
import importlib.util
import json
from pathlib import Path
import sys
import threading
import time
import types
import unittest
from dataclasses import replace
import numpy as np
sys.dont_write_bytecode = True
HERE = Path(__file__).resolve().parents[1]
package = types.ModuleType('ptz_tracker_modular')
package.__path__ = [str(HERE/'ptz_tracker_modular')]
sys.modules['ptz_tracker_modular'] = package
from ptz_tracker_modular.frame_time import FrameClock
from ptz_tracker_modular.inspection_runtime import CropContext, CropWorker, check_stamp, current_detector, provenance
from ptz_tracker_modular.inspection_input import adapt_result
from ptz_tracker_modular.inspection_input import InspectionVisual
BOX = (8., 8., 48., 48.)
OWNER = (123, 7, 99.125, 0)
SOURCE = ('decoder', 'epoch1', 0)
SCORES = (('multirotor_uav', .94), ('fixed_wing_uav', .02), ('bird', .02), ('manned_aircraft', .02))
def stamp(seq=1, at=50., camera=0, epoch='epoch1'):
return FrameClock(camera, 'decoder', epoch).observe(source_seq=seq,
mono_before_ns=round(at*1e9), mono_after_ns=round(at*1e9), utc_ns=round((at+50)*1e9))
class RuntimeTests(unittest.TestCase):
def setUp(self):
self.worker = CropWorker((0, 2, 4, 6, 8, 10))
self.ctx = CropContext(0, 1, OWNER, SOURCE, 'b'*64)
self.worker.bind(self.ctx)
rng = np.random.default_rng(1)
self.frame = rng.integers(0, 256, (64, 64, 3), dtype=np.uint8)
def submit(self, *, ctx=None, seq=1, at=50., occluded=False, bbox=BOX):
ctx = ctx or self.ctx
return self.worker.submit(ctx, stamp(seq, at, ctx.camera, ctx.source[1]), self.frame,
bbox, now=at, occluded=occluded)
def test_real_crop_copies_exact_pixels_and_original_stamp(self):
self.assertTrue(self.submit())
original = self.frame[8:48, 8:48].copy()
self.frame[:] = 0
def classifier(pixels):
np.testing.assert_array_equal(pixels, original)
self.assertFalse(pixels.flags.writeable)
return SCORES
self.assertTrue(self.worker.run_one(classifier, clock=lambda:50.1))
st, rec = self.worker.take_stamped(self.ctx, now=50.2)
self.assertEqual((rec.source_seq, rec.observed_at, rec.shape), (1, 100., (64, 64)))
self.assertEqual(st.decode_mono_ns, 50_000_000_000)
self.assertFalse(rec.occluded)
self.assertGreater(rec.sharpness, 0)
def test_unknown_occlusion_quality_remains_unusable(self):
self.assertTrue(self.submit(occluded=None))
self.worker.run_one(lambda p:SCORES, clock=lambda:50.1)
self.assertTrue(self.worker.take(self.ctx, now=50.2).occluded)
def test_low_score_callback_cannot_hide_source_clipping(self):
self.assertTrue(self.submit(bbox=(0., 8., 40., 48.)))
self.worker.run_one(lambda p:SCORES, clock=lambda:50.1)
self.assertTrue(self.worker.take(self.ctx, now=50.2).clipped)
def test_slow_classifier_does_not_lock_submit_or_poll(self):
self.submit()
entered, release = threading.Event(), threading.Event()
def classify(pixels):
entered.set()
self.assertTrue(release.wait(2))
return SCORES
t = threading.Thread(target=lambda:self.worker.run_one(classify, clock=lambda:50.1))
t.start()
try:
self.assertTrue(entered.wait(1))
self.assertTrue(self.submit(seq=2, at=50.05))
self.assertIsNone(self.worker.take(self.ctx, now=50.1))
self.assertFalse(self.worker.run_one(lambda p:SCORES, clock=lambda:50.1))
self.assertEqual(self.worker.counts(), (1, 0))
finally:
release.set(); t.join(2)
self.assertFalse(t.is_alive())
def test_six_camera_queue_is_bounded_and_fair(self):
contexts = [replace(self.ctx, camera=c) for c in (0, 2, 4, 6, 8, 10)]
for c in contexts:
self.worker.bind(c)
self.assertTrue(self.submit(ctx=c))
for seq in range(2, 100):
self.assertTrue(self.submit(seq=seq, at=50.+seq*.001))
order = []
for _ in range(6):
self.assertTrue(self.worker.run_one(lambda p:SCORES, clock=lambda:50.2))
# Metadata results can be taken without retaining image buffers.
for c in contexts:
r = self.worker.take(c, now=50.2)
if r: order.append((r.camera, r.source_seq))
self.assertEqual(order, [(0,99),(2,1),(4,1),(6,1),(8,1),(10,1)])
self.assertEqual(self.worker.counts(), (0,0))
def test_old_inflight_answer_cannot_survive_revoke_rebind_aba(self):
self.submit()
def classify(p):
self.worker.revoke(0); self.worker.bind(self.ctx)
return SCORES
self.assertFalse(self.worker.run_one(classify, clock=lambda:50.1))
self.assertIsNone(self.worker.take(self.ctx, now=50.1))
def test_old_context_poll_cannot_consume_new_owner_result(self):
new=replace(self.ctx,inspection_id=2,owner=(124,8,100.,0))
self.worker.bind(new)
self.submit(ctx=new)
self.assertTrue(self.worker.run_one(lambda p:SCORES,clock=lambda:50.1))
self.assertIsNone(self.worker.take(self.ctx,now=50.2))
self.assertIsNotNone(self.worker.take(new,now=50.2))
def test_owner_source_model_or_session_change_drops_old_completion(self):
for changed in (replace(self.ctx, owner=(124,8,100.,0)),
replace(self.ctx, source=('decoder','epoch2',0)),
replace(self.ctx, classifier_sha='c'*64), replace(self.ctx, inspection_id=2)):
self.worker.bind(self.ctx); self.submit()
self.assertFalse(self.worker.run_one(lambda p:(self.worker.bind(changed) or SCORES), clock=lambda:50.1))
self.assertIsNone(self.worker.take(changed, now=50.1))
def test_stale_start_does_not_call_model(self):
self.submit()
self.assertFalse(self.worker.run_one(lambda p:self.fail('model called'), clock=lambda:50.651))
def test_completion_and_take_recheck_original_monotonic_age(self):
self.submit()
clock = [50.1]
def classify(p): clock[0]=50.651; return SCORES
self.assertFalse(self.worker.run_one(classify, clock=lambda:clock[0]))
self.submit(seq=2, at=51.)
self.assertTrue(self.worker.run_one(lambda p:SCORES, clock=lambda:51.1))
self.assertIsNone(self.worker.take(self.ctx, now=51.651))
def test_exception_retains_unknown_and_next_job_can_run(self):
self.submit()
def bad(p): raise RuntimeError('synthetic model error')
self.assertFalse(self.worker.run_one(bad, clock=lambda:50.1))
self.assertIsNone(self.worker.take(self.ctx, now=50.1))
self.submit(seq=2, at=50.2)
self.assertTrue(self.worker.run_one(lambda p:SCORES, clock=lambda:50.3))
def test_duplicate_reverse_time_wrong_epoch_and_excess_crop_refused(self):
self.assertTrue(self.submit())
self.assertFalse(self.submit())
self.assertFalse(self.submit(seq=2, at=49.9))
wrong = replace(self.ctx, source=('decoder','epoch2',0))
self.assertFalse(self.submit(ctx=wrong, seq=2, at=50.1))
small = CropWorker((0,), max_pixels=10); small.bind(self.ctx)
self.assertFalse(small.submit(self.ctx, stamp(), self.frame, BOX, now=50.))
def test_binding_cannot_be_learned_from_untrusted_result(self):
result = types.SimpleNamespace(inspection_stamp=stamp(), inspection_owner=OWNER)
state = {}
self.assertNotEqual(provenance(state,result,None,camera=0,seq=1,owner=OWNER,mono=50.,visual_only=False),'')
self.assertNotIn('inspection_source_binding', state)
def test_detector_monotonic_deadline_duplicate_and_clock_epoch(self):
s = stamp(); result = types.SimpleNamespace(inspection_stamp=s,inspection_owner=OWNER)
state = {'inspection_source_binding':SOURCE}
self.assertEqual(provenance(state,result,None,camera=0,seq=1,owner=OWNER,mono=50.1,visual_only=False),'')
self.assertTrue(current_detector(state,50.65))
self.assertFalse(current_detector(state,50.651))
self.assertNotEqual(provenance(state,result,None,camera=0,seq=1,owner=OWNER,mono=50.2,visual_only=False),'')
result.inspection_stamp = replace(stamp(2,50.2),clock_epoch=1)
self.assertNotEqual(provenance(state,result,None,camera=0,seq=2,owner=OWNER,mono=50.2,visual_only=False),'')
def test_visual_stamp_required_and_age_independent_of_wall(self):
state = {'inspection_source_binding':SOURCE}
old = types.SimpleNamespace(inspection_stamp=stamp(), inspection_owner=OWNER, captured_at=999.)
self.assertNotEqual(provenance(state,None,old,camera=0,seq=1,owner=OWNER,mono=50.251,visual_only=True),'')
self.assertEqual(provenance(state,None,old,camera=0,seq=1,owner=OWNER,mono=50.2,visual_only=True),'')
def test_stamp_future_or_foreign_owner_rejected(self):
for kw in ({'now':49.9}, {'seq':2}, {'camera':2}, {'owner':(1,)}, {'binding':('other','epoch1',0)}):
args=dict(camera=0,seq=1,owner=OWNER,expected_owner=OWNER,binding=SOURCE,now=50.,age=.65)
args.update(kw)
self.assertFalse(check_stamp(stamp(),**args))
def test_visual_adapter_cannot_restamp_sequence_owner_or_wall_time(self):
s=stamp(); original=types.SimpleNamespace(source_seq=1,captured_at=100.,owner=OWNER,result=object())
self.assertIs(InspectionVisual(original,s,OWNER).result,original.result)
for bad in (replace(s,source_seq=2),replace(s,decode_utc_ns=101_000_000_000)):
with self.assertRaises(ValueError): InspectionVisual(original,bad,OWNER)
with self.assertRaises(ValueError): InspectionVisual(original,s,(1,))
def test_malformed_or_unbounded_score_map_is_bounded_and_refused(self):
invalid = ((),(('drone',1.),),tuple((n,float('nan')) for n,v in SCORES),
tuple((n,1.) for n,v in SCORES),('oops',)*4)
for i,scores in enumerate(invalid):
self.assertTrue(self.submit(seq=i+1,at=50.+i*.01))
self.assertFalse(self.worker.run_one(lambda p:scores,clock=lambda:50.1))
self.submit(seq=10,at=50.2)
def unbounded(p):
while True: yield ('bird',.25)
self.assertFalse(self.worker.run_one(unbounded,clock=lambda:50.3))
if __name__ == '__main__':
unittest.main(verbosity=2)
Loading…
Cancel
Save