Add UNKNOWN inspection policy and frame provenance

feature/unknown-r3-server-integration
Ярослав Карташов 2 weeks ago
parent 587658c3b1
commit f3e2f8374f

@ -0,0 +1,69 @@
"""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

@ -0,0 +1,187 @@
"""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))

@ -0,0 +1,267 @@
"""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=(",", ":"))

@ -0,0 +1,172 @@
"""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):
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.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
return self.crops.submit(pending[0],stamp,frame,pending[1],now=self.clock(),occluded=occluded)

@ -0,0 +1,237 @@
"""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):
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 = {}, {}
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
@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.current(ticket))
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

@ -0,0 +1,64 @@
"""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)

@ -0,0 +1,240 @@
"""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()}

@ -0,0 +1,77 @@
"""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)

@ -0,0 +1,265 @@
"""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)

@ -0,0 +1,211 @@
"""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