@trillboards/edge-sdk 0.2.140 → 0.2.150

package/README.md

@@ -16,11 +16,11 @@ The Edge SDK runs on digital signage hardware (kiosks, vending machines, billboa
 
 - **Audience sensing** — on-device face detection, gaze tracking, emotion analysis, foot traffic estimation via ONNX models (no cloud dependency)
 - **Ad delivery** — Chromium browser lifecycle, display management, VAST/VPAID ad rendering
-- **Federated learning** — privacy-preserving on-device model training with sparse gradient uploads
+- **Federated learning** — on-device model training with sparse gradient uploads
 - **Cloud inference** — Gemini Vision scene analysis, content moderation, contextual targeting
 - **Device management** — heartbeat, health monitoring, auto-recovery, signal buffering for offline resilience
 
-All audience data stays on-device. Only aggregated, anonymized metrics are transmitted.
+Detection runs on the device, and the agent transmits the audience metrics. In local-sensing mode (the Sense Anything connector) it also sends Trillboards a still frame with each alert-worthy moment it analyses, and in cloud-sensing mode every frame it asks the cloud model to read; Trillboards keeps those frames for 400 days.
 
 ## Configuration
 

package/deploy/detector/pyproject.toml

@@ -10,7 +10,7 @@ name = "trillboards-detector"
 # constant, a `labels.py`-only change survives `uv tool install` AND
 # `uv tool install --force`; move the version and a bare `uv tool install`
 # reinstalls. See `stamp_version.py`.
-version = "0.2.0+src.2c3db7881945"
+version = "0.2.0+src.6d43cf061068"
 description = "On-device object-detector service for the Trillboards BYO-CCTV connector (loopback HTTP, ONNX Runtime)."
 requires-python = ">=3.10"
 
@@ -29,11 +29,29 @@ requires-python = ">=3.10"
 # `docs/runbooks/cctv-detector-tier.md` §Runtime. A bump is a re-measurement,
 # not a version-number edit.
 dependencies = [
-  "onnxruntime==1.29.0",
   "numpy==2.5.2",
   "pillow==12.3.0",
 ]
 
+# Exactly one runtime per managed tool environment. Both wheels export the
+# same Python module; installing them together is not a CPU fallback strategy.
+# Normal provisioners select [cpu], or [cuda] on a detected NVIDIA Windows host.
+[project.optional-dependencies]
+cpu = ["onnxruntime==1.29.0"]
+cuda = [
+  "onnxruntime-gpu[cuda,cudnn]==1.29.0",
+  "nvidia-cublas==13.8.0.4",
+  "nvidia-cuda-nvrtc==13.4.92",
+  "nvidia-cuda-runtime==13.4.92",
+  "nvidia-cudnn-cu13==9.27.0.42",
+  "nvidia-cufft==12.4.0.43",
+  "nvidia-curand==10.4.4.72",
+  "nvidia-nvjitlink==13.4.92",
+]
+
+[tool.uv]
+conflicts = [[{extra = "cpu"}, {extra = "cuda"}]]
+
 [project.scripts]
 trillboards-detector = "trillboards_detector.cli:main"
 

package/deploy/detector/tests/test_execution.py

@@ -0,0 +1,124 @@
+"""Provider-policy tests, not detector accuracy or simulated model evidence."""
+import unittest
+
+from trillboards_detector.execution import CPU, CUDA, LocalOrtSession
+
+
+class Session:
+    def __init__(self, providers, failure=None, demote=False):
+        self.providers, self.failure, self.demote = providers, failure, demote
+        self.inputs = []
+
+    def get_providers(self):
+        return self.providers
+
+    def run(self, outputs, inputs):
+        self.inputs.append(inputs)
+        if self.failure:
+            raise RuntimeError(self.failure)
+        if self.demote:
+            self.providers = [CPU]
+        return inputs
+
+
+class Runtime:
+    def __init__(self, available=(CUDA, CPU), *, init_error=False,
+                 gpu_failure=None, cpu_failure=None, silent_cpu=False, demote=False):
+        self.available = list(available)
+        self.init_error, self.gpu_failure, self.cpu_failure = init_error, gpu_failure, cpu_failure
+        self.silent_cpu, self.demote = silent_cpu, demote
+        self.calls, self.preloads = [], 0
+
+    def get_available_providers(self):
+        return self.available
+
+    def preload_dlls(self, directory):
+        assert directory == ""
+        self.preloads += 1
+
+    def InferenceSession(self, model, *, sess_options, providers):
+        self.calls.append((model, sess_options, providers))
+        if CUDA in providers and self.init_error:
+            raise RuntimeError("driver unavailable")
+        gpu = CUDA in providers
+        return Session([CPU] if gpu and self.silent_cpu else providers,
+                       self.gpu_failure if gpu else self.cpu_failure,
+                       self.demote if gpu else False)
+
+
+class TestLocalExecution(unittest.TestCase):
+    def test_prefers_available_cuda_and_keeps_cpu_kernels(self):
+        r = Runtime()
+        s = LocalOrtSession(r, b"immutable model", object())
+        self.assertEqual(r.calls[0][2], [CUDA, CPU])
+        self.assertEqual(r.preloads, 1)
+        self.assertEqual(s.acceleration["backend"], "cuda")
+        self.assertIsNone(s.acceleration["fallback_reason"])
+
+    def test_cpu_only_host_never_attempts_cuda(self):
+        r = Runtime((CPU,))
+        s = LocalOrtSession(r, b"model", None)
+        self.assertEqual([c[2] for c in r.calls], [[CPU]])
+        self.assertEqual(s.acceleration["backend"], "cpu")
+        self.assertIn("unavailable", s.acceleration["fallback_reason"])
+        self.assertIsNone(s._model_bytes)
+
+    def test_explicit_cpu_is_the_rollback_even_on_nvidia(self):
+        r = Runtime()
+        s = LocalOrtSession(r, b"model", None, "cpu")
+        self.assertEqual([c[2] for c in r.calls], [[CPU]])
+        self.assertEqual(s.acceleration["fallback_reason"], "CPU explicitly selected")
+
+    def test_missing_driver_is_a_visible_cpu_fallback(self):
+        r = Runtime(init_error=True)
+        s = LocalOrtSession(r, b"same weights", None)
+        self.assertEqual([c[2] for c in r.calls], [[CUDA, CPU], [CPU]])
+        self.assertIn("driver unavailable", s.acceleration["fallback_reason"])
+
+    def test_ort_silent_cpu_initialization_is_not_reported_as_gpu(self):
+        s = LocalOrtSession(Runtime(silent_cpu=True), b"model", None)
+        self.assertEqual(s.acceleration["backend"], "cpu")
+        self.assertIn("CPU-only", s.acceleration["fallback_reason"])
+
+    def test_gpu_failure_retries_identical_captured_input_and_model_once(self):
+        model = b"exact original immutable weights"
+        r = Runtime(gpu_failure="out of GPU memory")
+        s = LocalOrtSession(r, model, None)
+        original = {"frame": object()}
+        self.assertIs(s.run(["detections"], original), original)
+        self.assertEqual(len(r.calls), 2)
+        self.assertIs(r.calls[1][0], model)
+        self.assertEqual(s.acceleration["backend"], "cpu")
+        self.assertIn("out of GPU memory", s.acceleration["fallback_reason"])
+        s.run(["detections"], original)
+        self.assertEqual(len(r.calls), 2)
+        self.assertIsNone(s._model_bytes)
+
+    def test_cpu_failure_propagates_not_a_false_negative(self):
+        s = LocalOrtSession(Runtime(gpu_failure="gpu failed", cpu_failure="bad input"), b"model", None)
+        with self.assertRaisesRegex(RuntimeError, "bad input"):
+            s.run([], {})
+
+    def test_ort_internal_runtime_demotion_updates_actual_backend(self):
+        s = LocalOrtSession(Runtime(demote=True), b"model", None)
+        s.run([], {})
+        self.assertEqual(s.acceleration["backend"], "cpu")
+        self.assertIn("demoted", s.acceleration["fallback_reason"])
+
+    def test_unknown_backend_is_rejected(self):
+        with self.assertRaises(ValueError):
+            LocalOrtSession(Runtime(), b"model", None, "intel")
+
+    def test_health_snapshot_is_safe_during_cpu_session_replacement(self):
+        s = LocalOrtSession(Runtime(), b"model", None)
+        s._session = None
+        s._acceleration = {"requested": "auto", "backend": "initializing_cpu",
+                           "providers": [], "fallback_reason": "GPU failed"}
+        self.assertEqual(s.acceleration["backend"], "initializing_cpu")
+        external = s.acceleration
+        external["providers"].append("invented")
+        self.assertEqual(s.acceleration["providers"], [])
+
+
+if __name__ == "__main__":
+    unittest.main()

package/deploy/detector/tests/test_model_identity.py

@@ -0,0 +1,80 @@
+"""Selected model identity, with real registry logic and tiny fixture artifacts."""
+import hashlib
+import json
+import tempfile
+import unittest
+from pathlib import Path
+
+from trillboards_detector.errors import ModelVerificationError
+from trillboards_detector.registry import ModelEntry, ModelRegistry
+from trillboards_detector.server import WireError, parse_expected_model, build_detect_response
+# CI discovers this as tests.test_model_identity; the narrow detector lane
+# discovers it as a top-level module. Resolve the sibling in either context.
+if __package__:
+    from .test_registry import GENERAL, PPE, FakeSession, MB
+else:
+    from test_registry import GENERAL, PPE, FakeSession, MB
+
+
+class ModelIdentityTests(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.tmp.cleanup)
+        self.paths = {v.model_name: Path(self.tmp.name) / (v.model_name + '.onnx') for v in (GENERAL, PPE)}
+        for name, path in self.paths.items():
+            path.write_bytes(('explicit fixture artifact ' + name).encode())
+        self.sessions = []
+        def factory(entry):
+            session = FakeSession(entry.vocabulary)
+            session.model_sha256 = hashlib.sha256(entry.path.read_bytes()).hexdigest()
+            self.sessions.append(session)
+            original = session.detect
+            def detect(*args):
+                result = original(*args)
+                result.model_hashes = {session.model_name: session.model_sha256}
+                return result
+            session.detect = detect
+            return session
+        self.registry = ModelRegistry([ModelEntry(GENERAL, self.paths['general'], pinned=True), ModelEntry(PPE, self.paths['ppe'])],
+                                      factory, lambda _session: None, 2048 * MB, log=lambda _line: None)
+        self.registry.refresh()
+
+    def pin(self, name):
+        return {'modelId': name, 'sha256': hashlib.sha256(self.paths[name].read_bytes()).hexdigest()}
+
+    def test_matching_pin_reports_session_hash(self):
+        batch = self.registry.detect(b'fixture image', .5, {'person'}, expected_model=self.pin('general'))
+        self.assertEqual(build_detect_response(batch)['model_hashes'], {'general': self.pin('general')['sha256']})
+
+    def test_wrong_hash_refused_before_requested_image_inference(self):
+        pin = {**self.pin('general'), 'sha256': 'f' * 64}
+        with self.assertRaises(ModelVerificationError):
+            self.registry.detect(b'fixture image', .5, {'person'}, expected_model=pin)
+        self.assertEqual(self.sessions[0].calls, [])
+
+    def test_explicit_specialist_is_not_replaced_by_general_shared_class(self):
+        batch = self.registry.detect(b'fixture image', .5, {'person'}, expected_model=self.pin('ppe'))
+        self.assertEqual(batch.models, ['ppe'])
+        self.assertEqual(self.sessions[0].calls, [])
+
+    def test_unknown_model_or_classes_are_refused(self):
+        for pin, classes in [({'modelId': 'missing', 'sha256': 'a' * 64}, {'person'}), (self.pin('general'), {'glove'})]:
+            with self.assertRaises(ModelVerificationError):
+                self.registry.detect(b'fixture image', .5, classes, expected_model=pin)
+
+    def test_disk_replacement_cannot_be_attributed_to_old_loaded_pin(self):
+        old = self.pin('general')
+        self.paths['general'].write_bytes(b'changed artifact with a different size')
+        with self.assertRaises(ModelVerificationError):
+            self.registry.detect(b'fixture image', .5, {'person'}, expected_model=old)
+
+    def test_wire_pin_must_be_explicit_and_complete(self):
+        self.assertIsNone(parse_expected_model(b'{}'))
+        self.assertEqual(parse_expected_model(json.dumps({'expected_model': self.pin('general')}).encode()), self.pin('general'))
+        for value in [None, {}, {'modelId': 'general', 'sha256': 'A' * 64}, {**self.pin('general'), 'extra': True}]:
+            with self.assertRaises(WireError):
+                parse_expected_model(json.dumps({'expected_model': value}).encode())
+
+
+if __name__ == '__main__':
+    unittest.main()

package/deploy/detector/tests/test_registry.py

@@ -654,6 +654,24 @@ class TestDownIsNeverEmpty(RegistryCase):
 class TestSnapshotIsCheapAndHonest(RegistryCase):
     """`/health` reports which models are resident and must not load one."""
 
+    def test_health_reports_actual_backend_and_cpu_fallback_reason(self):
+        self.write_artifact("general")
+        reg = self.registry([GENERAL], pinned="general")
+        reg.refresh()
+        session = self.sessions["general"]
+        session.acceleration = {"requested": "auto", "backend": "cuda",
+                                "providers": ["CUDAExecutionProvider", "CPUExecutionProvider"],
+                                "fallback_reason": None}
+        first = reg.snapshot()["models"]["general"]
+        self.assertEqual(first["providers"][0], "CUDAExecutionProvider")
+        session.acceleration = {"requested": "auto", "backend": "cpu",
+                                "providers": ["CPUExecutionProvider"],
+                                "fallback_reason": "GPU inference failed"}
+        second = reg.snapshot()["models"]["general"]
+        self.assertEqual(second["providers"], ["CPUExecutionProvider"])
+        self.assertEqual(second["acceleration"]["fallback_reason"], "GPU inference failed")
+        self.assertEqual(self.sessions["general"].calls, [])
+
     def test_the_snapshot_loads_nothing_and_infers_nothing(self):
         self.write_artifact("general")
         self.write_artifact("ppe")

package/deploy/detector/tests/test_server.py

@@ -114,8 +114,10 @@ class ServerCase(unittest.TestCase):
         # 20 ms poll: `shutdown()` blocks until the loop notices, and the
         # 500 ms default turns a 22-test suite into 11 s of pure waiting.
         threading.Thread(target=lambda: server.serve_forever(poll_interval=0.02), daemon=True).start()
-        self.addCleanup(server.shutdown)
+        # Cleanup runs last-in-first-out. Stop the selector thread before
+        # closing its socket, otherwise Windows emits WinError 10038.
         self.addCleanup(server.server_close)
+        self.addCleanup(server.shutdown)
         host, port = server.server_address[:2]
         return f"http://{host}:{port}"
 

package/deploy/detector/tests/test_version_stamp.py

@@ -135,7 +135,10 @@ class TestVersionStamp(unittest.TestCase):
             )
             before = _load_stamper(root).expected_version()[2]
             for path in list((root / "trillboards_detector").rglob("*.py")) + [root / "pyproject.toml"]:
-                path.write_bytes(path.read_bytes().replace(b"\n", b"\r\n"))
+                # Start from normalized bytes: a checkout already using CRLF
+                # must not become CRCRLF, which is a different text document.
+                raw = path.read_bytes().replace(b"\r\n", b"\n").replace(b"\r", b"\n")
+                path.write_bytes(raw.replace(b"\n", b"\r\n"))
             after = _load_stamper(root).expected_version()[2]
             self.assertEqual(before, after, "CRLF alone moved the fingerprint")
 

package/deploy/detector/trillboards_detector/_version.py

@@ -13,5 +13,5 @@ human sets.
 """
 
 BASE_VERSION = "0.2.0"
-SOURCE_FINGERPRINT = "2c3db7881945"
-VERSION = "0.2.0+src.2c3db7881945"
+SOURCE_FINGERPRINT = "6d43cf061068"
+VERSION = "0.2.0+src.6d43cf061068"

package/deploy/detector/trillboards_detector/cli.py

@@ -103,6 +103,8 @@ def build_parser() -> argparse.ArgumentParser:
         ),
     )
     s.add_argument("--poll-interval", type=float, default=DEFAULT_POLL_INTERVAL_S)
+    s.add_argument("--accelerator", choices=("auto", "cpu"), default="auto",
+                   help="prefer compatible local NVIDIA CUDA, otherwise CPU; cpu is an explicit rollback")
     s.add_argument("--log-file", default=None, help="also write to this file (Windows has no task stdout)")
     s.add_argument("--verbose", action="store_true")
     return p
@@ -157,6 +159,7 @@ def main(argv: "list[str] | None" = None) -> int:
         poll_interval_s=args.poll_interval,
         ram_budget_bytes=ram_budget_bytes,
         log=LOG.info,
+        accelerator=args.accelerator,
     )
     loader.start()
 

package/deploy/detector/trillboards_detector/detections.py

@@ -57,6 +57,9 @@ class DetectionBatch:
     #: The model(s) that produced this, in the order they ran. Exactly one
     #: element for a batch off a single session; N for a merged one.
     models: list[str] = field(default_factory=list)
+    # Derived from the exact bytes used to create each ONNX session, not a
+    # request pin, a catalogue entry, or a later read of the mutable model path.
+    model_hashes: dict[str, str] = field(default_factory=dict)
 
 
 def merge_batches(batches: "list[DetectionBatch]") -> DetectionBatch:
@@ -92,6 +95,10 @@ def merge_batches(batches: "list[DetectionBatch]") -> DetectionBatch:
         merged.degenerate_dropped += b.degenerate_dropped
         merged.unnamed_class_dropped += b.unnamed_class_dropped
         merged.models.extend(b.models)
+        for model, digest in b.model_hashes.items():
+            if model in merged.model_hashes and merged.model_hashes[model] != digest:
+                raise ValueError("one frame cannot merge different artifacts under one model id")
+            merged.model_hashes[model] = digest
     return merged
 
 

package/deploy/detector/trillboards_detector/errors.py

@@ -37,6 +37,10 @@ class ModelContractError(RuntimeError):
     """
 
 
+class ModelVerificationError(RuntimeError):
+    """A selected artifact is not the one in the loaded inference session."""
+
+
 class UnknownClasses(ValueError):
     """The caller named classes no resident-or-present model can emit.
 

package/deploy/detector/trillboards_detector/execution.py

@@ -0,0 +1,109 @@
+"""Select one local ORT backend and expose every CPU fallback.
+
+The model bytes and outputs are unchanged. This module has no runtime imports,
+so provider policy can be tested without downloading models or CUDA libraries.
+"""
+from __future__ import annotations
+
+import logging
+
+LOG = logging.getLogger(__name__)
+CPU = "CPUExecutionProvider"
+CUDA = "CUDAExecutionProvider"
+
+
+class LocalOrtSession:
+    """One ORT session; at most one CPU retry after a GPU failure.
+
+    Keep the original immutable bytes only while GPU fallback is possible. An
+    OTA replacing the file must never change the model used for the retry.
+    """
+
+    def __init__(self, runtime, model_bytes: bytes, options, accelerator="auto"):
+        if accelerator not in ("auto", "cpu"):
+            raise ValueError("accelerator must be auto or cpu")
+        self._runtime, self._options = runtime, options
+        self._model_bytes = model_bytes
+        self.requested = accelerator
+        self.fallback_reason = None
+        self._cuda_active = False
+        self._acceleration = {"requested": accelerator, "backend": "starting",
+                              "providers": [], "fallback_reason": None}
+        available = runtime.get_available_providers()
+        if accelerator == "auto" and CUDA in available:
+            try:
+                preload = getattr(runtime, "preload_dlls", None)
+                if preload is not None:
+                    preload(directory="")
+                self._session = runtime.InferenceSession(
+                    model_bytes, sess_options=options, providers=[CUDA, CPU]
+                )
+                self._cuda_active = CUDA in self._session.get_providers()
+            except Exception as error:
+                self._cpu("CUDA initialization failed: " + str(error))
+            else:
+                if not self._cuda_active:
+                    self._cpu("CUDA initialization returned a CPU-only session")
+        else:
+            self._session = runtime.InferenceSession(
+                model_bytes, sess_options=options, providers=[CPU]
+            )
+            self._model_bytes = None
+            self.fallback_reason = (
+                "CPU explicitly selected" if accelerator == "cpu"
+                else "CUDA provider unavailable; using the CPU runtime"
+            )
+        self._publish_acceleration()
+        LOG.info("[detector] local execution: %s", self.acceleration)
+
+    def _cpu(self, reason):
+        # A failed GPU attempt must not keep its allocation while CPU starts.
+        self._session = None
+        self._cuda_active = False
+        self.fallback_reason = reason[:1000]
+        self._acceleration = {"requested": self.requested, "backend": "initializing_cpu",
+                              "providers": [], "fallback_reason": self.fallback_reason}
+        LOG.warning("[detector] GPU unavailable; CPU fallback: %s", self.fallback_reason)
+        self._session = self._runtime.InferenceSession(
+            self._model_bytes, sess_options=self._options, providers=[CPU]
+        )
+        self._model_bytes = None
+        self._publish_acceleration()
+
+    def _publish_acceleration(self):
+        providers = list(self._session.get_providers())
+        self._acceleration = {
+            "requested": self.requested,
+            "backend": "cuda" if CUDA in providers else "cpu",
+            "providers": providers,
+            "fallback_reason": self.fallback_reason,
+        }
+
+    @property
+    def acceleration(self):
+        # Health must not dereference the transient None session while another
+        # thread is constructing CPU fallback. Publish one immutable snapshot.
+        return {**self._acceleration, "providers": list(self._acceleration["providers"])}
+
+    def run(self, outputs, inputs):
+        try:
+            result = self._session.run(outputs, inputs)
+            # ORT may demote internally without raising. Do not keep reporting
+            # CUDA just because construction originally requested it.
+            if self._cuda_active and CUDA not in self._session.get_providers():
+                self._cuda_active = False
+                self._model_bytes = None
+                self.fallback_reason = "ORT demoted GPU inference to CPU"
+                LOG.warning("[detector] %s", self.fallback_reason)
+            self._publish_acceleration()
+            return result
+        except Exception as error:
+            if not self._cuda_active:
+                raise
+            self._cpu("GPU inference failed: " + str(error))
+            # Same captured input, once. If CPU also fails, propagate the error;
+            # never turn a failed inference into a negative observation.
+            return self._session.run(outputs, inputs)
+
+    def __getattr__(self, name):
+        return getattr(self._session, name)

package/deploy/detector/trillboards_detector/loader.py

@@ -128,6 +128,7 @@ class DetectorLoader:
         ram_budget_bytes: "int | None" = None,
         vocabularies: "tuple[ModelVocabulary, ...]" = BUILTIN_VOCABULARIES,
         log=print,
+        accelerator: str = "auto",
     ):
         # `ram_budget_bytes=None` is NOT a default policy — it is the absence of
         # one, and the registry refuses every portfolio decision in that state
@@ -137,6 +138,7 @@ class DetectorLoader:
         self.model_path = model_path
         self.model_name = model_name
         self._intra_op_threads = intra_op_threads
+        self._accelerator = accelerator
         self._poll_interval_s = poll_interval_s
         self._log = log
 
@@ -154,7 +156,7 @@ class DetectorLoader:
     # ── the two halves that need a real runtime ──────────────────────────────
 
     def _build_session(self, entry: ModelEntry) -> OnnxDetector:
-        return OnnxDetector(entry.path, entry.vocabulary, self._intra_op_threads)
+        return OnnxDetector(entry.path, entry.vocabulary, self._intra_op_threads, self._accelerator)
 
     def _probe(self, session: OnnxDetector) -> None:
         """PROVE IT. A session that constructs is not a session that infers.
@@ -276,6 +278,7 @@ class DetectorLoader:
             "input",
             "classes",
             "providers",
+            "acceleration",
             "output_layout",
             "preprocessing",
         ):
@@ -283,8 +286,8 @@ class DetectorLoader:
                 payload[key] = pinned[key]
         return payload
 
-    def detect(self, jpeg: bytes, min_confidence: float, wanted: "set[str] | None") -> DetectionBatch:
-        return self.registry.detect(jpeg, min_confidence, wanted)
+    def detect(self, jpeg: bytes, min_confidence: float, wanted: "set[str] | None", expected_model=None) -> DetectionBatch:
+        return self.registry.detect(jpeg, min_confidence, wanted, expected_model=expected_model)
 
     # ── the loop ─────────────────────────────────────────────────────────────
 

package/deploy/detector/trillboards_detector/registry.py

@@ -62,7 +62,7 @@ import time
 from pathlib import Path
 
 from .detections import DetectionBatch, merge_batches
-from .errors import DetectorNotReady, ModelContractError, UnknownClasses
+from .errors import DetectorNotReady, ModelContractError, ModelVerificationError, UnknownClasses
 from .labels import ClassIndex, ModelVocabulary, normalize_class_name
 
 #: Per-model residency states. `absent` and `idle` are new and they are
@@ -379,7 +379,7 @@ class ModelRegistry:
 
     # ── the request path ─────────────────────────────────────────────────────
 
-    def detect(self, jpeg: bytes, min_confidence: float, wanted: "set[str] | None") -> DetectionBatch:
+    def detect(self, jpeg: bytes, min_confidence: float, wanted: "set[str] | None", expected_model=None) -> DetectionBatch:
         """Run every model this request needs, in catalogue order, and merge.
 
         ALL OR NOTHING. If any model in the plan cannot be made resident — the
@@ -391,7 +391,16 @@ class ModelRegistry:
         quieter venue, which is the single failure this component exists to
         prevent.
         """
-        plan = self.class_index().assign(wanted)
+        if expected_model is None:
+            plan = self.class_index().assign(wanted)
+        else:
+            selected = self._states.get(expected_model["modelId"])
+            if selected is None:
+                raise ModelVerificationError("selected model is not in this box's catalogue")
+            vocabulary = selected.entry.vocabulary
+            if wanted is not None and not wanted.issubset(vocabulary.class_names):
+                raise ModelVerificationError("selected model cannot answer all requested classes")
+            plan = [(vocabulary, wanted)]
         if not plan:
             raise DetectorNotReady(
                 "no model on this box can answer that request; "
@@ -400,6 +409,10 @@ class ModelRegistry:
 
         acquired = self._acquire([vocabulary.model_name for vocabulary, _ in plan])
         try:
+            if expected_model is not None and (
+                len(acquired) != 1 or getattr(acquired[0], "model_sha256", None) != expected_model["sha256"]
+            ):
+                raise ModelVerificationError("loaded session does not match the selected artifact")
             batches = []
             for (vocabulary, classes), session in zip(plan, acquired):
                 state = self._states[vocabulary.model_name]
@@ -707,6 +720,10 @@ class ModelRegistry:
                     row["input"] = f"{spec.width}x{spec.height}"
                     row["classes"] = spec.num_classes
                     row["providers"] = list(spec.providers)
+                    acceleration = getattr(s.session, "acceleration", None)
+                    if isinstance(acceleration, dict):
+                        row["acceleration"] = acceleration
+                        row["providers"] = acceleration["providers"]
                     # WHICH DECODE AND WHICH PREPROCESSING PRODUCED THIS MODEL'S
                     # NUMBERS. Three layouts now reach this service and their
                     # preprocessors are not interchangeable, so a confidence with
@@ -805,8 +822,13 @@ def read_process_rss() -> "tuple[int, str] | None":
 
             counters = _Counters()
             counters.cb = ctypes.sizeof(_Counters)
-            handle = ctypes.windll.kernel32.GetCurrentProcess()
-            if ctypes.windll.psapi.GetProcessMemoryInfo(
+            current_process = ctypes.windll.kernel32.GetCurrentProcess
+            current_process.restype = wintypes.HANDLE
+            memory_info = ctypes.windll.psapi.GetProcessMemoryInfo
+            memory_info.argtypes = [wintypes.HANDLE, ctypes.POINTER(_Counters), wintypes.DWORD]
+            memory_info.restype = wintypes.BOOL
+            handle = current_process()
+            if memory_info(
                 handle, ctypes.byref(counters), counters.cb
             ):
                 return int(counters.WorkingSetSize), "psapi-workingset"