@trillboards/edge-sdk 0.2.203 → 0.2.207

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/deploy/detector/pyproject.toml +1 -1
  2. package/deploy/detector/tests/test_colors_v2.py +17 -0
  3. package/deploy/detector/tests/test_server.py +196 -0
  4. package/deploy/detector/tests/test_task_registry.py +129 -0
  5. package/deploy/detector/trillboards_detector/_version.py +2 -2
  6. package/deploy/detector/trillboards_detector/colors.py +24 -0
  7. package/deploy/detector/trillboards_detector/loader.py +3 -0
  8. package/deploy/detector/trillboards_detector/registry.py +49 -0
  9. package/deploy/detector/trillboards_detector/server.py +71 -1
  10. package/dist/CloudSensingManager.d.ts.map +1 -1
  11. package/dist/CloudSensingManager.js +25 -3
  12. package/dist/CloudSensingManager.js.map +1 -1
  13. package/dist/EdgeAgent.js +1 -1
  14. package/dist/LocalDetectorClient.d.ts +4 -0
  15. package/dist/LocalDetectorClient.d.ts.map +1 -1
  16. package/dist/LocalDetectorClient.js +36 -0
  17. package/dist/LocalDetectorClient.js.map +1 -1
  18. package/dist/NativeReadiness.d.ts +41 -0
  19. package/dist/NativeReadiness.d.ts.map +1 -0
  20. package/dist/NativeReadiness.js +109 -0
  21. package/dist/NativeReadiness.js.map +1 -0
  22. package/dist/SensingProfileClient.d.ts +8 -0
  23. package/dist/SensingProfileClient.d.ts.map +1 -1
  24. package/dist/SensingProfileClient.js +48 -4
  25. package/dist/SensingProfileClient.js.map +1 -1
  26. package/dist/diagnose.d.ts +1 -1
  27. package/dist/diagnose.js +1 -1
  28. package/dist/localSensing.d.ts +16 -0
  29. package/dist/localSensing.d.ts.map +1 -1
  30. package/dist/localSensing.js +133 -5
  31. package/dist/localSensing.js.map +1 -1
  32. package/dist/sensingRunMode.d.ts.map +1 -1
  33. package/dist/sensingRunMode.js +3 -1
  34. package/dist/sensingRunMode.js.map +1 -1
  35. package/package.json +3 -3
  36. package/retained/ProfileAuthorityClient.cjs +8 -2
  37. package/retained/__tests__/runtime.test.cjs +140 -2
  38. package/retained/manager.cjs +22 -11
  39. package/retained/pilot-profile-client.cjs +21 -3
@@ -10,7 +10,7 @@ name = "trillboards-detector"
10
10
  # constant, a `labels.py`-only change survives `uv tool install` AND
11
11
  # `uv tool install --force`; move the version and a bare `uv tool install`
12
12
  # reinstalls. See `stamp_version.py`.
13
- version = "0.2.0+src.42da00861e2b"
13
+ version = "0.2.0+src.befcd33e8e35"
14
14
  description = "On-device object-detector service for the Trillboards BYO-CCTV connector (loopback HTTP, ONNX Runtime)."
15
15
  requires-python = ">=3.10"
16
16
 
@@ -1,6 +1,7 @@
1
1
  """Bounded colour contract; synthetic fixtures establish arithmetic, never field accuracy."""
2
2
  import importlib.util
3
3
  import unittest
4
+ from unittest.mock import patch
4
5
 
5
6
  from trillboards_detector.colors import validate_color_request, build_color_response
6
7
 
@@ -11,6 +12,22 @@ V2 = {"version": 2, "minScore": .25, "maxBoxes": 32, "hue": [[0, 255]],
11
12
 
12
13
 
13
14
  class BoundedColourContractTest(unittest.TestCase):
15
+ def test_readiness_with_no_colour_requirement_needs_no_decoder(self):
16
+ from trillboards_detector.colors import prepare_color_capabilities
17
+ self.assertEqual(prepare_color_capabilities([]), [])
18
+ with self.assertRaises(ValueError):
19
+ prepare_color_capabilities(["unsupported"])
20
+
21
+ @unittest.skipUnless(importlib.util.find_spec("numpy") and importlib.util.find_spec("PIL"),
22
+ "NumPy/Pillow unavailable for actual colour preparation")
23
+ def test_readiness_probes_both_actual_colour_kernels(self):
24
+ from trillboards_detector.colors import prepare_color_capabilities
25
+ caps = ["detection_colors_v2", "detection_colors_v1"]
26
+ self.assertEqual(prepare_color_capabilities(caps), caps)
27
+ with patch("trillboards_detector.colors.detection_color_fractions", return_value=((1, 1), [0.0])):
28
+ with self.assertRaises(RuntimeError):
29
+ prepare_color_capabilities(caps)
30
+
14
31
  def test_v1_request_and_response_are_unchanged(self):
15
32
  self.assertEqual(validate_color_request(V1), V1)
16
33
  self.assertEqual(build_color_response(V1, [2], [.08], "a" * 64, (160, 120)),
@@ -18,6 +18,11 @@ from __future__ import annotations
18
18
  import base64
19
19
  import json
20
20
  import socket
21
+ import tempfile
22
+ import threading
23
+ import sys
24
+ from pathlib import Path
25
+ from unittest.mock import patch
21
26
  import unittest
22
27
  import urllib.error
23
28
  import urllib.request
@@ -33,6 +38,8 @@ from trillboards_detector.labels import (
33
38
  VariantContract,
34
39
  )
35
40
  from trillboards_detector.server import DetectorServer, MAX_BODY_BYTES
41
+ from trillboards_detector.registry import ModelRegistry, ModelEntry, TaskModelContract
42
+ from trillboards_detector.loader import DetectorLoader
36
43
 
37
44
  JPEG = bytes([0xFF, 0xD8, 0xFF, 0xE0, 0x00, 0x10, 0x4A, 0x46])
38
45
 
@@ -111,6 +118,7 @@ class ServerCase(unittest.TestCase):
111
118
  import threading
112
119
 
113
120
  server = DetectorServer(("127.0.0.1", 0), loader, log_line=lambda _m: None)
121
+ self.last_server = server
114
122
  # 20 ms poll: `shutdown()` blocks until the loop notices, and the
115
123
  # 500 ms default turns a 22-test suite into 11 s of pure waiting.
116
124
  threading.Thread(target=lambda: server.serve_forever(poll_interval=0.02), daemon=True).start()
@@ -189,6 +197,194 @@ class ServerCase(unittest.TestCase):
189
197
  s.close()
190
198
 
191
199
 
200
+ class TestReadiness(ServerCase):
201
+ RF_SHA = "8e8197112112b79d7cc5d0a94ecef659c05317a658aadc7c7643374c539d7615"
202
+ POSE_SHA = "5c0a4bf67953e6d2ac43ce15e77dc9d5d354ae18430a47d2c5963a7bc5683e3c"
203
+ VEHICLE_SHA = "682c4b3255f94bc82dda6f47ae10d73082f40fa33c3535b7b7f7e87d3cab20a8"
204
+
205
+ def loader(self):
206
+ tmp = tempfile.TemporaryDirectory(); self.addCleanup(tmp.cleanup)
207
+ root = Path(tmp.name)
208
+ pose = TaskModelContract("rtmpose_m_body7", "pose_coco17", self.POSE_SHA, 100 * 1024**2, "test-pose")
209
+ vehicle = TaskModelContract("siglip2_l16_vehicle_end_v1", "vehicle_end_orientation", self.VEHICLE_SHA, 100 * 1024**2, "test-vehicle")
210
+ self.loads, self.probes = [], []
211
+ def factory(entry):
212
+ self.loads.append(entry.name)
213
+ return type("Session", (), {"model_id": entry.name, "model_sha256": getattr(entry.vocabulary, "sha256", self.RF_SHA)})()
214
+ entries = []
215
+ for vocab in (RFDETR_MEDIUM, pose, vehicle):
216
+ file = root / (vocab.model_name + ".onnx"); file.write_bytes(b"fake model")
217
+ entries.append(ModelEntry(vocab, file, pinned=vocab is RFDETR_MEDIUM))
218
+ reg = ModelRegistry(entries, factory, lambda session: self.probes.append(session.model_id), 1000 * 1024**2, log=lambda line: None)
219
+ reg.refresh()
220
+ loader = object.__new__(DetectorLoader); loader.registry = reg
221
+ return loader
222
+
223
+ def payload(self):
224
+ return {"version": 1, "models": [{"modelId": "rtmpose_m_body7", "sha256": self.POSE_SHA},
225
+ {"modelId": "rfdetr_medium", "sha256": self.RF_SHA},
226
+ {"modelId": "siglip2_l16_vehicle_end_v1", "sha256": self.VEHICLE_SHA}],
227
+ "capabilities": ["detection_colors_v1", "detection_colors_v2"]}
228
+
229
+ def ready(self, url, body, probe=None):
230
+ with patch("trillboards_detector.server.prepare_color_capabilities", probe or (lambda caps: list(caps)), create=True):
231
+ return self.request(url + "/ready", "POST", body=body)
232
+
233
+ def test_ready_uses_actual_loader_registry_and_retains_probed_sessions(self):
234
+ loader = self.loader(); url = self.serve(loader); body = self.payload()
235
+ status, result = self.ready(url, body)
236
+ self.assertEqual(status, 200)
237
+ self.assertEqual(set(result), {"version", "ready", "models", "capabilities"})
238
+ self.assertEqual(result, {"version": 1, "ready": True, "capabilities": body["capabilities"],
239
+ "models": [{**body["models"][0], "task": "pose_coco17"}, {**body["models"][1], "task": "object_detection"},
240
+ {**body["models"][2], "task": "vehicle_end_orientation"}]})
241
+ self.assertEqual(self.loads, ["rfdetr_medium", "rtmpose_m_body7", "siglip2_l16_vehicle_end_v1"])
242
+ self.assertEqual(self.probes, self.loads)
243
+ self.assertEqual(self.ready(url, body)[0], 200)
244
+ self.assertEqual(len(self.loads), 3)
245
+ self.assertTrue(all(s.in_flight == 0 and s.detect_count == 0 for s in loader.registry._states.values()))
246
+
247
+ def test_health_stays_cheap_before_readiness(self):
248
+ loader = self.loader(); url = self.serve(loader)
249
+ status, _ = self.request(url + "/health")
250
+ self.assertEqual(status, 200)
251
+ self.assertEqual(self.loads, ["rfdetr_medium"])
252
+ self.assertEqual(self.probes, ["rfdetr_medium"])
253
+
254
+ def test_ready_refuses_bad_shape_and_unsupported_capabilities(self):
255
+ loader = self.loader(); url = self.serve(loader)
256
+ for change in (lambda b: b.update(version=True), lambda b: b.update(image_b64="forbidden"),
257
+ lambda b: b.update(models=[]), lambda b: b.update(capabilities=["other"]),
258
+ lambda b: b.update(capabilities=["detection_colors_v1"] * 2)):
259
+ body = self.payload(); change(body)
260
+ with self.subTest(body=body):
261
+ self.assertEqual(self.ready(url, body)[0], 400)
262
+ self.assertEqual(self.loads, ["rfdetr_medium"])
263
+
264
+ def test_ready_refuses_wrong_selected_hash(self):
265
+ loader = self.loader(); body = self.payload(); body["models"][0]["sha256"] = "b" * 64
266
+ self.assertEqual(self.ready(self.serve(loader), body)[0], 409)
267
+ self.assertEqual(self.loads, ["rfdetr_medium"])
268
+
269
+ def test_ready_missing_artifact_is_503_not_partial_ready(self):
270
+ loader = self.loader(); loader.registry._states["rtmpose_m_body7"].entry.path.unlink()
271
+ status, body = self.ready(self.serve(loader), self.payload())
272
+ self.assertEqual(status, 503)
273
+ self.assertNotIn("ready", body)
274
+ self.assertTrue(all(s.in_flight == 0 for s in loader.registry._states.values()))
275
+
276
+ def test_ready_colour_backend_failure_is_503_before_model_load(self):
277
+ loader = self.loader()
278
+ def missing(caps):
279
+ raise ImportError("controlled colour backend missing")
280
+ status, body = self.ready(self.serve(loader), self.payload(), missing)
281
+ self.assertEqual(status, 503); self.assertNotIn("ready", body)
282
+ self.assertEqual(self.loads, ["rfdetr_medium"])
283
+
284
+ def test_timed_out_owner_does_not_accumulate_admission_waiters(self):
285
+ loader = self.loader(); url = self.serve(loader); server = self.last_server
286
+ entered = threading.Event(); calls = []; handlers = []; errors = []; outcomes = []
287
+ acquire = loader.registry._acquire
288
+ def observed_acquire(names):
289
+ calls.append(list(names)); entered.set()
290
+ return acquire(names)
291
+ loader.registry._acquire = observed_acquire
292
+ process = server.process_request_thread
293
+ def observed_handler(*args):
294
+ handlers.append(threading.current_thread())
295
+ return process(*args)
296
+ server.process_request_thread = observed_handler
297
+ def handled_error(*args):
298
+ error = sys.exc_info()[1]
299
+ if not isinstance(error, (BrokenPipeError, ConnectionResetError)):
300
+ errors.append(repr(error))
301
+ server.handle_error = handled_error
302
+ body = self.payload(); body["capabilities"] = []
303
+ def attempt():
304
+ req = urllib.request.Request(url + "/ready", json.dumps(body).encode(), method="POST",
305
+ headers={"Content-Type": "application/json"})
306
+ try:
307
+ with urllib.request.urlopen(req, timeout=.5) as response:
308
+ return response.status
309
+ except urllib.error.HTTPError as error:
310
+ with error:
311
+ error.read()
312
+ return error.code
313
+ except TimeoutError:
314
+ return "timeout"
315
+ client = threading.Thread(target=lambda: outcomes.append(attempt()))
316
+ # The actual registry admission lock blocks preparation without any model.
317
+ loader.registry._admission.acquire()
318
+ try:
319
+ client.start()
320
+ self.assertTrue(entered.wait(2), "owner never reached actual registry admission")
321
+ client.join(2)
322
+ self.assertFalse(client.is_alive())
323
+ self.assertEqual(outcomes, ["timeout"])
324
+ owner_still_active = handlers[0].is_alive()
325
+ retry_statuses = [attempt(), attempt()]
326
+ calls_before_release = len(calls)
327
+ self.assertEqual(self.request(url + "/health")[0], 200)
328
+ finally:
329
+ loader.registry._admission.release()
330
+ client.join(2)
331
+ for handler in handlers:
332
+ handler.join(2)
333
+ self.assertTrue(owner_still_active, "client timeout unexpectedly cancelled server preparation")
334
+ self.assertEqual(retry_statuses, [503, 503], f"native admission calls={calls_before_release}; owner active after timeout={owner_still_active}")
335
+ self.assertEqual(calls_before_release, 1, "retries queued extra native preparation work")
336
+ self.assertFalse(any(handler.is_alive() for handler in handlers))
337
+ self.assertEqual(errors, [])
338
+ # A disconnected successful owner must release the gate too.
339
+ self.assertEqual(self.ready(url, body)[0], 200)
340
+ self.assertTrue(all(state.in_flight == 0 for state in loader.registry._states.values()))
341
+
342
+ def test_ready_preparation_gate_releases_after_colour_failure(self):
343
+ loader = self.loader(); url = self.serve(loader); server = self.last_server
344
+ logged = threading.Event(); release_log = threading.Event(); handlers = []
345
+ process = server.process_request_thread
346
+ def observed_handler(*args):
347
+ handlers.append(threading.current_thread())
348
+ return process(*args)
349
+ server.process_request_thread = observed_handler
350
+ def log_after_response(message):
351
+ if message.endswith("POST /ready -> 503") and not logged.is_set():
352
+ logged.set()
353
+ release_log.wait() # The client path always releases this in finally.
354
+ server.log_line = log_after_response
355
+ def failed_probe(caps):
356
+ raise RuntimeError("controlled colour probe failure")
357
+ try:
358
+ status, body = self.ready(url, self.payload(), failed_probe)
359
+ self.assertEqual(status, 503)
360
+ self.assertEqual(body, {"error": "requested colour capability failed its preparation probe"})
361
+ self.assertTrue(logged.wait(2), "owner did not reach logging after response delivery")
362
+ self.assertTrue(handlers[0].is_alive(), "owner must still be blocked in response logging")
363
+ status, body = self.ready(url, self.payload())
364
+ self.assertEqual(status, 200, f"gate_locked_after_response={server.preparation_gate.locked()}; response={body}; loads={self.loads}")
365
+ finally:
366
+ release_log.set()
367
+ for handler in handlers:
368
+ handler.join(2)
369
+ self.assertFalse(any(handler.is_alive() for handler in handlers))
370
+ self.assertEqual(self.ready(url, self.payload())[0], 200)
371
+ self.assertTrue(all(state.in_flight == 0 for state in loader.registry._states.values()))
372
+
373
+ def test_ready_preparation_gate_releases_after_model_errors(self):
374
+ loader = self.loader(); url = self.serve(loader)
375
+ for error, status in [(DetectorNotReady("controlled absent model"), 503),
376
+ (RuntimeError("controlled preparation failure"), 500)]:
377
+ with self.subTest(status=status), patch.object(loader, "prepare_models", side_effect=error):
378
+ self.assertEqual(self.ready(url, self.payload())[0], status)
379
+ self.assertEqual(self.ready(url, self.payload())[0], 200)
380
+ wrong = self.payload(); wrong["models"][0]["sha256"] = "b" * 64
381
+ self.assertEqual(self.ready(url, wrong)[0], 409)
382
+ self.assertEqual(self.ready(url, self.payload())[0], 200)
383
+
384
+ def test_ready_does_not_invent_model_preparation_on_old_loader(self):
385
+ self.assertEqual(self.ready(self.serve(FakeLoader()), self.payload())[0], 503)
386
+
387
+
192
388
  class TestHealth(ServerCase):
193
389
  def test_ready_is_200_and_never_runs_inference(self):
194
390
  loader = FakeLoader()
@@ -1,5 +1,6 @@
1
1
  """Non-box tasks share the detector's real admission and eviction policy."""
2
2
  import tempfile
3
+ import threading
3
4
  import unittest
4
5
  from pathlib import Path
5
6
  from trillboards_detector.errors import DetectorNotReady, ModelVerificationError
@@ -29,6 +30,134 @@ class TaskAdmissionTest(unittest.TestCase):
29
30
  reg.refresh()
30
31
  return reg
31
32
 
33
+ def _load_while_refresh_waits(self, mutation=None):
34
+ reg = self.registry(800 * 1024**2)
35
+ state = reg._states["pose_test"]
36
+ observed = threading.Event()
37
+ admission = reg._admission
38
+ logs, errors, sessions = [], [], []
39
+ reg._log = logs.append
40
+
41
+ class ObservedAdmission:
42
+ def __enter__(inner):
43
+ if threading.current_thread() is worker:
44
+ observed.set()
45
+ admission.acquire()
46
+ return inner
47
+
48
+ def __exit__(inner, *exc):
49
+ admission.release()
50
+
51
+ def refresh():
52
+ try:
53
+ reg._refresh_one(state.entry)
54
+ except BaseException as err:
55
+ errors.append(err)
56
+
57
+ worker = threading.Thread(target=refresh, daemon=True)
58
+ reg._admission = ObservedAdmission()
59
+ try:
60
+ with reg._admission:
61
+ worker.start()
62
+ self.assertTrue(observed.wait(2), "watcher did not reach admission")
63
+ sessions = reg._acquire(["pose_test"])
64
+ self.assertIs(state.session, sessions[0])
65
+ if mutation == "changed":
66
+ self.pose.write_bytes(b"changed task artifact")
67
+ elif mutation == "deleted":
68
+ self.pose.unlink()
69
+ worker.join(2)
70
+ self.assertFalse(worker.is_alive(), "watcher did not finish")
71
+ self.assertEqual(errors, [])
72
+ if mutation is None:
73
+ self.assertIs(state.session, sessions[0])
74
+ self.assertEqual(state.state, "ready")
75
+ self.assertFalse(any("artifact changed" in line for line in logs))
76
+ elif mutation == "changed":
77
+ self.assertIsNone(state.session)
78
+ stat = self.pose.stat()
79
+ self.assertEqual(state.stamp, (stat.st_size, stat.st_mtime_ns))
80
+ self.assertEqual(state.state, "idle")
81
+ else:
82
+ self.assertIsNone(state.session)
83
+ self.assertEqual(state.state, "absent")
84
+ self.assertFalse(state.present)
85
+ self.assertEqual(state.in_flight, 1)
86
+ self.assertEqual(self.loads.count("pose_test"), 1)
87
+ finally:
88
+ if sessions:
89
+ reg._release(["pose_test"])
90
+ worker.join(2)
91
+ self.assertEqual(state.in_flight, 0)
92
+
93
+ def test_refresh_waiting_on_admission_preserves_completed_same_stamp_load(self):
94
+ self._load_while_refresh_waits()
95
+
96
+ def test_refresh_waiting_on_admission_observes_changed_artifact(self):
97
+ self._load_while_refresh_waits("changed")
98
+
99
+ def test_refresh_waiting_on_admission_observes_deleted_artifact(self):
100
+ self._load_while_refresh_waits("deleted")
101
+
102
+ def test_readiness_warms_exact_models_and_releases_leases_without_camera_inference(self):
103
+ reg = self.registry(800 * 1024**2)
104
+ requested = [{"modelId": "rfdetr_medium", "sha256": SHA}, {"modelId": "pose_test", "sha256": SHA}]
105
+ expected = [{**requested[0], "task": "object_detection"}, {**requested[1], "task": "pose_coco17"}]
106
+ self.assertEqual(reg.prepare_models(requested), expected)
107
+ self.assertEqual(self.loads, ["rfdetr_medium", "pose_test"])
108
+ self.assertEqual(reg.prepare_models(requested), expected)
109
+ self.assertEqual(self.loads, ["rfdetr_medium", "pose_test"])
110
+ for state in reg._states.values():
111
+ self.assertEqual(state.in_flight, 0)
112
+ self.assertEqual(state.detect_count, 0)
113
+
114
+ def test_readiness_refuses_wrong_task_pin_before_loading(self):
115
+ reg = self.registry(800 * 1024**2)
116
+ with self.assertRaises(ModelVerificationError):
117
+ reg.prepare_models([{"modelId": "pose_test", "sha256": "b" * 64}])
118
+ self.assertEqual(self.loads, ["rfdetr_medium"])
119
+
120
+ def test_readiness_refuses_malformed_duplicate_and_unknown_models(self):
121
+ reg = self.registry(800 * 1024**2)
122
+ for models in ([], None, [{"modelId": "pose_test", "sha256": SHA}] * 2,
123
+ [{"modelId": "pose_test", "sha256": "bad"}],
124
+ [{"modelId": "pose_test", "sha256": SHA, "extra": True}]):
125
+ with self.subTest(models=models), self.assertRaises(ValueError):
126
+ reg.prepare_models(models)
127
+ with self.assertRaises(ModelVerificationError):
128
+ reg.prepare_models([{"modelId": "unknown", "sha256": SHA}])
129
+ self.assertEqual(self.loads, ["rfdetr_medium"])
130
+
131
+ def test_readiness_verifies_loaded_session_hash_and_releases_every_lease(self):
132
+ reg = self.registry(800 * 1024**2)
133
+ reg._session_factory = lambda entry: type("Wrong", (), {"model_sha256": "b" * 64})()
134
+ with self.assertRaises(ModelVerificationError):
135
+ reg.prepare_models([{"modelId": "rfdetr_medium", "sha256": SHA}, {"modelId": "pose_test", "sha256": SHA}])
136
+ self.assertTrue(all(s.in_flight == 0 for s in reg._states.values()))
137
+
138
+ def test_readiness_keeps_the_existing_ram_admission_refusal(self):
139
+ reg = self.registry(700 * 1024**2)
140
+ with self.assertRaises(DetectorNotReady):
141
+ reg.prepare_models([{"modelId": "pose_test", "sha256": SHA}])
142
+ self.assertEqual(self.loads, ["rfdetr_medium"])
143
+
144
+ def test_readiness_probe_failure_is_not_partial_readiness(self):
145
+ reg = self.registry(800 * 1024**2)
146
+ def fail_probe(session):
147
+ raise RuntimeError("controlled task probe failure")
148
+ reg._probe = fail_probe
149
+ with self.assertRaises(DetectorNotReady):
150
+ reg.prepare_models([{"modelId": "rfdetr_medium", "sha256": SHA}, {"modelId": "pose_test", "sha256": SHA}])
151
+ self.assertTrue(all(s.in_flight == 0 for s in reg._states.values()))
152
+ self.assertEqual(reg._states["pose_test"].state, "unavailable")
153
+
154
+ def test_readiness_missing_task_artifact_refuses(self):
155
+ reg = self.registry(800 * 1024**2)
156
+ self.pose.unlink()
157
+ with self.assertRaises(DetectorNotReady):
158
+ reg.prepare_models([{"modelId": "pose_test", "sha256": SHA}])
159
+ self.assertEqual(self.loads, ["rfdetr_medium"])
160
+
32
161
  def test_pose_is_not_a_detection_class_and_is_lazy(self):
33
162
  reg=self.registry(800*1024**2)
34
163
  self.assertEqual(reg.class_index().model_names,("rfdetr_medium",))
@@ -13,5 +13,5 @@ human sets.
13
13
  """
14
14
 
15
15
  BASE_VERSION = "0.2.0"
16
- SOURCE_FINGERPRINT = "42da00861e2b"
17
- VERSION = "0.2.0+src.42da00861e2b"
16
+ SOURCE_FINGERPRINT = "befcd33e8e35"
17
+ VERSION = "0.2.0+src.befcd33e8e35"
@@ -94,6 +94,30 @@ def detection_color_fractions(jpeg, boxes, request):
94
94
  return (width, height), fractions
95
95
 
96
96
 
97
+ def prepare_color_capabilities(capabilities):
98
+ """Exercise the existing decoder and selected HSV kernels on one synthetic pixel."""
99
+ if (not isinstance(capabilities, list) or len(capabilities) > 2
100
+ or any(cap not in ("detection_colors_v1", "detection_colors_v2") for cap in capabilities)
101
+ or len(set(capabilities)) != len(capabilities)):
102
+ raise ValueError("unsupported or duplicate colour preparation capability")
103
+ if not capabilities:
104
+ return []
105
+ from PIL import Image
106
+ encoded = io.BytesIO()
107
+ Image.new("RGB", (1, 1), (0, 0, 0)).save(encoded, format="JPEG")
108
+ for capability in capabilities:
109
+ version = 1 if capability == "detection_colors_v1" else 2
110
+ request = {"version": version, "minScore": .25, "maxBoxes": 1,
111
+ "hue": [[0, 255]], "minSaturation": 0, "minValue": 0}
112
+ if version == 2:
113
+ request.update(maxSaturation=255, maxValue=255)
114
+ request = validate_color_request(request)
115
+ size, fractions = detection_color_fractions(encoded.getvalue(), [[0, 0, 1, 1]], request)
116
+ if size != (1, 1) or fractions != [1.0]:
117
+ raise RuntimeError("colour preparation probe did not produce its known synthetic fraction")
118
+ return list(capabilities)
119
+
120
+
97
121
  def build_color_response(request, indices, fractions, image_sha256, frame_size):
98
122
  if len(indices) != len(fractions) or any(
99
123
  isinstance(f, bool) or not isinstance(f, float) or not 0 <= f <= 1 for f in fractions):
@@ -312,6 +312,9 @@ class DetectorLoader:
312
312
  payload[key] = pinned[key]
313
313
  return payload
314
314
 
315
+ def prepare_models(self, models: list) -> list:
316
+ return self.registry.prepare_models(models)
317
+
315
318
  def detect(self, jpeg: bytes, min_confidence: float, wanted: "set[str] | None", expected_model=None) -> DetectionBatch:
316
319
  return self.registry.detect(jpeg, min_confidence, wanted, expected_model=expected_model)
317
320
 
@@ -187,6 +187,22 @@ class _ModelState:
187
187
  return self.session is not None
188
188
 
189
189
 
190
+ def validate_preparation_models(models):
191
+ """A closed, bounded set of exact model pins; no image or field answers."""
192
+ if not isinstance(models, list) or not 1 <= len(models) <= 8:
193
+ raise ValueError("models needs 1..8 exact model pins")
194
+ names = set()
195
+ for model in models:
196
+ if (not isinstance(model, dict) or set(model) != {"modelId", "sha256"}
197
+ or not isinstance(model["modelId"], str) or not 1 <= len(model["modelId"]) <= 128
198
+ or not isinstance(model["sha256"], str)
199
+ or re.fullmatch(r"[0-9a-f]{64}", model["sha256"]) is None
200
+ or model["modelId"] in names):
201
+ raise ValueError("models needs unique model IDs and lowercase SHA-256 pins")
202
+ names.add(model["modelId"])
203
+ return models
204
+
205
+
190
206
  class ModelRegistry:
191
207
  """The name -> session map, its class index, and the residency policy."""
192
208
 
@@ -335,6 +351,11 @@ class ModelRegistry:
335
351
  self._refresh_one(entry)
336
352
 
337
353
  def _refresh_one(self, entry: ModelEntry) -> None:
354
+ # Observe the artifact and state only after pending lazy loads finish.
355
+ with self._admission:
356
+ self._refresh_one_admitted(entry)
357
+
358
+ def _refresh_one_admitted(self, entry: ModelEntry) -> None:
338
359
  state = self._states[entry.name]
339
360
  stamp = _file_stamp(entry.path)
340
361
 
@@ -405,6 +426,34 @@ class ModelRegistry:
405
426
 
406
427
  # ── the request path ─────────────────────────────────────────────────────
407
428
 
429
+ def prepare_models(self, models: list) -> list:
430
+ """Acquire and probe the entire selected set without camera inference.
431
+
432
+ Uses the same admission, hash verification and synthetic load probe as
433
+ inference. Leases cover the full set, then end; successful sessions stay
434
+ resident under the existing LRU policy.
435
+ """
436
+ models = validate_preparation_models(models)
437
+ names = [model["modelId"] for model in models]
438
+ for model in models:
439
+ state = self._states.get(model["modelId"])
440
+ if state is None:
441
+ raise ModelVerificationError("selected model is not in this box's catalogue")
442
+ selected_sha = getattr(state.entry.vocabulary, "sha256", None)
443
+ if selected_sha is not None and selected_sha != model["sha256"]:
444
+ raise ModelVerificationError("selected task hash differs from its pinned contract")
445
+ sessions = self._acquire(names)
446
+ try:
447
+ proof = []
448
+ for model, session in zip(models, sessions):
449
+ if getattr(session, "model_sha256", None) != model["sha256"]:
450
+ raise ModelVerificationError("loaded model hash differs from the selected pin")
451
+ contract = self._states[model["modelId"]].entry.vocabulary
452
+ proof.append({**model, "task": getattr(contract, "task", "object_detection")})
453
+ return proof
454
+ finally:
455
+ self._release(names)
456
+
408
457
  def detect(self, jpeg: bytes, min_confidence: float, wanted: "set[str] | None", expected_model=None) -> DetectionBatch:
409
458
  """Run every model this request needs, in catalogue order, and merge.
410
459
 
@@ -38,7 +38,8 @@ from .actor_tracking import TrackingError, validate_tracking_request
38
38
  from .actor_identity import MODEL_ID as APPEARANCE_MODEL_ID, MODEL_SHA256 as APPEARANCE_SHA256, PREPROCESSING as APPEARANCE_PREPROCESSING, checked_appearance
39
39
  from .tasks import RTMPOSE_MODEL_ID, RTMPOSE_SHA256, RTMPOSE_PREPROCESSING, COCO17
40
40
  from .actor_action_wire import parse_actor_action_request, validate_actor_action_response
41
- from .colors import validate_color_request
41
+ from .colors import validate_color_request, prepare_color_capabilities
42
+ from .registry import validate_preparation_models
42
43
  from .vehicle_end import validate_vehicle_end_request
43
44
  from ._version import VERSION
44
45
  from .errors import DetectorNotReady, ModelVerificationError, UnknownClasses
@@ -76,6 +77,27 @@ class WireError(Exception):
76
77
  self.message = message
77
78
 
78
79
 
80
+ def parse_ready_request(raw: bytes):
81
+ try:
82
+ payload = json.loads(raw.decode("utf-8"))
83
+ except (UnicodeDecodeError, json.JSONDecodeError):
84
+ raise WireError(400, "readiness body must be JSON") from None
85
+ if (not isinstance(payload, dict) or set(payload) != {"version", "models", "capabilities"}
86
+ or type(payload["version"]) is not int or payload["version"] != 1):
87
+ raise WireError(400, "readiness needs version 1, models and capabilities only")
88
+ try:
89
+ models = validate_preparation_models(payload["models"])
90
+ except ValueError as err:
91
+ raise WireError(400, str(err)) from None
92
+ caps = payload["capabilities"]
93
+ if (not isinstance(caps, list) or len(caps) > 2
94
+ or any(not isinstance(cap, str) or cap not in
95
+ ("detection_colors_v1", "detection_colors_v2") for cap in caps)
96
+ or len(set(caps)) != len(caps)):
97
+ raise WireError(400, "unsupported or duplicate readiness capability")
98
+ return models, caps
99
+
100
+
79
101
  def parse_detect_request(raw: bytes) -> tuple[bytes, float, "list[str] | None"]:
80
102
  """Body bytes -> (jpeg, min_confidence, requested class names or None for all).
81
103
 
@@ -416,6 +438,8 @@ class DetectorHandler(BaseHTTPRequestHandler):
416
438
  self._actor_actions()
417
439
  elif self._path() == "/vehicle-end":
418
440
  self._vehicle_end()
441
+ elif self._path() == "/ready":
442
+ self._ready()
419
443
  elif self._path() == "/health":
420
444
  self._json(405, {"error": "/health is a GET"})
421
445
  else:
@@ -424,6 +448,51 @@ class DetectorHandler(BaseHTTPRequestHandler):
424
448
  def _path(self) -> str:
425
449
  return self.path.split("?", 1)[0].rstrip("/") or "/"
426
450
 
451
+ def _ready(self) -> None:
452
+ try:
453
+ models, caps = parse_ready_request(self._read_body())
454
+ except WireError as err:
455
+ self._json(err.status, {"error": err.message})
456
+ return
457
+ prepare = getattr(self.server.loader, "prepare_models", None)
458
+ if not callable(prepare):
459
+ self._json(503, {"error": "model preparation is unavailable in this detector build"})
460
+ return
461
+ # Client timeouts do not cancel a native load. Never queue another
462
+ # preparation behind that owner; retries get a bounded busy refusal.
463
+ gate = self.server.preparation_gate
464
+ if not gate.acquire(blocking=False):
465
+ self._json(503, {"error": "native preparation is busy"})
466
+ return
467
+ try:
468
+ try:
469
+ prepared_caps = prepare_color_capabilities(caps)
470
+ except Exception:
471
+ raise WireError(503, "requested colour capability failed its preparation probe") from None
472
+ try:
473
+ proof = prepare(models)
474
+ except ModelVerificationError as err:
475
+ raise WireError(409, str(err)) from None
476
+ except DetectorNotReady as err:
477
+ raise WireError(503, str(err)) from None
478
+ except Exception:
479
+ raise WireError(500, "model preparation failed") from None
480
+ if (not isinstance(proof, list) or len(proof) != len(models)
481
+ or prepared_caps != caps
482
+ or any(not isinstance(row, dict) or set(row) != {"modelId", "sha256", "task"}
483
+ or row["modelId"] != model["modelId"] or row["sha256"] != model["sha256"]
484
+ or not isinstance(row["task"], str) or not row["task"]
485
+ for model, row in zip(models, proof))):
486
+ raise WireError(500, "model preparation returned an invalid proof")
487
+ status, payload = 200, {"version": 1, "ready": True, "models": proof, "capabilities": prepared_caps}
488
+ except WireError as err:
489
+ status, payload = err.status, {"error": err.message}
490
+ finally:
491
+ gate.release()
492
+ # Native work has ended. Response writes and logging may outlive the
493
+ # client's receipt; they must not make its next preparation look busy.
494
+ self._json(status, payload)
495
+
427
496
  # ── /health ──────────────────────────────────────────────────────────────
428
497
 
429
498
  def _health(self) -> None:
@@ -834,6 +903,7 @@ class DetectorServer(ThreadingHTTPServer):
834
903
  def __init__(self, address, loader, log_line=print, actor_tracker=None):
835
904
  super().__init__(address, DetectorHandler)
836
905
  self.loader = loader
906
+ self.preparation_gate = threading.Lock()
837
907
  self.actor_tracker = actor_tracker
838
908
  self.log_line = log_line
839
909