"""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=(",", ":"))