feat(perception): prewarm RF-DETR before source admission

src/k1link/perception/detector.py

@@ -101,6 +101,31 @@ class DetectorFrameTiming:
 DetectorTimingObserver = Callable[[DetectorFrameTiming], None]
 
 
+@dataclass(frozen=True, slots=True)
+class DetectorWarmupSnapshot:
+    completed: bool
+    inference_passes: int
+    preprocess_duration_ns: int
+    inference_transport_duration_ns: int
+    postprocess_duration_ns: int
+    total_duration_ns: int
+
+    def __post_init__(self) -> None:
+        durations = (
+            self.preprocess_duration_ns,
+            self.inference_transport_duration_ns,
+            self.postprocess_duration_ns,
+            self.total_duration_ns,
+        )
+        if (
+            self.completed is not True
+            or self.inference_passes != 1
+            or any(value < 0 for value in durations)
+            or sum(durations[:3]) != self.total_duration_ns
+        ):
+            raise DetectorProviderError("detector warmup snapshot is incompatible")
+
+
 class FrozenYoloxDetectorProvider:
     """One image payload produces one frozen inference request and proposal tuple."""
 
@@ -259,6 +284,50 @@ class RfDetrShadowDetectorProvider:
         self._proposal_count = 0
         self._rejected: Counter[str] = Counter()
         self._core_duration_ns = 0
+        self._warmup_started = False
+        self._warmup_snapshot: DetectorWarmupSnapshot | None = None
+
+    def warm_up(self) -> DetectorWarmupSnapshot:
+        """Prime preprocessing, transport and postprocessing before source admission."""
+
+        with self._lock:
+            if self._warmup_snapshot is not None:
+                return self._warmup_snapshot
+            if self._warmup_started:
+                raise DetectorProviderError("RF-DETR warmup is already in progress")
+            self._warmup_started = True
+        started_ns = int(self._clock_ns())
+        try:
+            image = np.zeros(
+                (self.config.source_height, self.config.source_width, 3),
+                dtype=np.uint8,
+            )
+            tensor = preprocess_raw_kb4_rf_detr(
+                image,
+                self.mask,
+                config=self.config,
+                resizer=self.resizer,
+            )
+            preprocessed_ns = int(self._clock_ns())
+            output = self.backend.infer(tensor)
+            inferred_ns = int(self._clock_ns())
+            postprocess_rf_detr(output, self.mask, config=self.config)
+            completed_ns = int(self._clock_ns())
+        except Exception:
+            with self._lock:
+                self._warmup_started = False
+            raise
+        snapshot = DetectorWarmupSnapshot(
+            completed=True,
+            inference_passes=1,
+            preprocess_duration_ns=max(0, preprocessed_ns - started_ns),
+            inference_transport_duration_ns=max(0, inferred_ns - preprocessed_ns),
+            postprocess_duration_ns=max(0, completed_ns - inferred_ns),
+            total_duration_ns=max(0, completed_ns - started_ns),
+        )
+        with self._lock:
+            self._warmup_snapshot = snapshot
+        return snapshot
 
     def detect(self, packet: SourcePacket) -> tuple[ObjectProposal2D, ...]:
         payload = packet.image_payload
@@ -357,6 +426,7 @@ __all__ = [
     "DetectorProviderSnapshot",
     "DetectorFrameTiming",
     "DetectorTimingObserver",
+    "DetectorWarmupSnapshot",
     "AllCocoYoloxDetectorProvider",
     "FrozenYoloxDetectorProvider",
     "RfDetrShadowDetectorProvider",

src/k1link/perception/m48s_reference_graph_runtime.py

@@ -13,6 +13,7 @@ from .baseline import load_m4_baseline
 from .detector import (
     RF_DETR_SHADOW_PROVIDER_ID,
     DetectorTimingObserver,
+    DetectorWarmupSnapshot,
     RfDetrShadowDetectorProvider,
 )
 from .geometry import (
@@ -64,6 +65,12 @@ class M48sReferenceGraphRuntime:
     graph: ReferencePerceptionGraphV2
     inference_backend: TritonRfDetrHttpInferenceBackend
 
+    def warm_up_detector(self) -> DetectorWarmupSnapshot:
+        detector = self.graph.detector
+        if not isinstance(detector, RfDetrShadowDetectorProvider):
+            raise M48sReferenceGraphRuntimeError("RF-DETR runtime detector changed before warmup")
+        return detector.warm_up()
+
     def close(self) -> None:
         self.inference_backend.close()
 
@@ -202,9 +209,7 @@ def _validate_provider_digests(
         raise M48sReferenceGraphRuntimeError("RF-DETR graph provider pins are incomplete")
     for role, path in pinned_files.items():
         if _sha256_file(path) != pins[role].sha256:
-            raise M48sReferenceGraphRuntimeError(
-                f"{role.value} provider profile digest changed"
-            )
+            raise M48sReferenceGraphRuntimeError(f"{role.value} provider profile digest changed")
 
 
 def _validate_detector_profile(path: Path) -> None:
@@ -216,13 +221,11 @@ def _validate_detector_profile(path: Path) -> None:
     except (OSError, KeyError, TypeError, json.JSONDecodeError) as exc:
         raise M48sReferenceGraphRuntimeError("RF-DETR profile is incomplete") from exc
     if (
-        document.get("schema_version")
-        != "missioncore.rf-detr-risk-shadow-profile/v0"
+        document.get("schema_version") != "missioncore.rf-detr-risk-shadow-profile/v0"
         or document.get("provider_id") != RF_DETR_SHADOW_PROVIDER_ID
         or model.get("model_id") != RF_DETR_MODEL_ID
         or model.get("model_version") != RF_DETR_MODEL_VERSION
-        or model.get("worker_006_rtx4090_tensorrt_11_engine_sha256")
-        != RF_DETR_ENGINE_SHA256
+        or model.get("worker_006_rtx4090_tensorrt_11_engine_sha256") != RF_DETR_ENGINE_SHA256
         or status.get("detector_load_gate_passed") is not True
         or status.get("production_accepted") is not False
         or any(
@@ -244,9 +247,7 @@ def _sha256_file(path: Path) -> str:
     except OSError as exc:
         raise M48sReferenceGraphRuntimeError("pinned RF-DETR graph input is missing") from exc
     if resolved.is_symlink() or not resolved.is_file():
-        raise M48sReferenceGraphRuntimeError(
-            "pinned RF-DETR graph input must be a regular file"
-        )
+        raise M48sReferenceGraphRuntimeError("pinned RF-DETR graph input must be a regular file")
     digest = hashlib.sha256()
     with resolved.open("rb") as handle:
         for chunk in iter(lambda: handle.read(1024 * 1024), b""):