@trillboards/edge-sdk 0.2.176 → 0.2.181

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 (49) hide show
  1. package/THIRD-PARTY-NOTICES.md +220 -0
  2. package/deploy/detector/bench/actor-appearance-qualified-v1.json +106 -0
  3. package/deploy/detector/bench/actor-appearance.md +52 -0
  4. package/deploy/detector/bench/export_actor_appearance.py +134 -0
  5. package/deploy/detector/bench/qualify_actor_appearance.py +77 -0
  6. package/deploy/detector/bench/qualify_actor_appearance_client.cjs +50 -0
  7. package/deploy/detector/bench/qualify_actor_appearance_wire.py +170 -0
  8. package/deploy/detector/bench/requirements-appearance-export.txt +4 -0
  9. package/deploy/detector/pyproject.toml +1 -1
  10. package/deploy/detector/tests/fixtures/actor-appearance-original-g326-v1.json +27105 -0
  11. package/deploy/detector/tests/test_actor_appearance_tracking.py +196 -0
  12. package/deploy/detector/tests/test_appearance_wire.py +80 -0
  13. package/deploy/detector/tests/test_loader.py +9 -7
  14. package/deploy/detector/trillboards_detector/_version.py +2 -2
  15. package/deploy/detector/trillboards_detector/actor_identity.py +323 -0
  16. package/deploy/detector/trillboards_detector/actor_tracking.py +163 -1
  17. package/deploy/detector/trillboards_detector/appearance.py +149 -0
  18. package/deploy/detector/trillboards_detector/loader.py +6 -0
  19. package/deploy/detector/trillboards_detector/registry.py +30 -1
  20. package/deploy/detector/trillboards_detector/server.py +56 -1
  21. package/deploy/detector/trillboards_detector/tasks.py +7 -1
  22. package/dist/ActorAppearance.d.ts +13 -0
  23. package/dist/ActorAppearance.d.ts.map +1 -0
  24. package/dist/ActorAppearance.js +17 -0
  25. package/dist/ActorAppearance.js.map +1 -0
  26. package/dist/ActorPerception.d.ts +2 -0
  27. package/dist/ActorPerception.d.ts.map +1 -1
  28. package/dist/ActorPerception.js +12 -5
  29. package/dist/ActorPerception.js.map +1 -1
  30. package/dist/ActorTracking.d.ts +3 -1
  31. package/dist/ActorTracking.d.ts.map +1 -1
  32. package/dist/ActorTracking.js +10 -3
  33. package/dist/ActorTracking.js.map +1 -1
  34. package/dist/DurableVlmCandidateSpool.d.ts.map +1 -1
  35. package/dist/DurableVlmCandidateSpool.js +31 -11
  36. package/dist/DurableVlmCandidateSpool.js.map +1 -1
  37. package/dist/EdgeAgent.js +1 -1
  38. package/dist/LocalDetectorClient.d.ts +2 -1
  39. package/dist/LocalDetectorClient.d.ts.map +1 -1
  40. package/dist/LocalDetectorClient.js +9 -2
  41. package/dist/LocalDetectorClient.js.map +1 -1
  42. package/dist/RuntimeModelSelection.d.ts.map +1 -1
  43. package/dist/RuntimeModelSelection.js +15 -1
  44. package/dist/RuntimeModelSelection.js.map +1 -1
  45. package/dist/diagnose.d.ts +1 -1
  46. package/dist/diagnose.js +1 -1
  47. package/package.json +2 -2
  48. package/retained/__tests__/actor-perception.test.cjs +29 -6
  49. package/retained/manager.cjs +20 -9
@@ -0,0 +1,196 @@
1
+ """Native source regression: event identity must not transfer with a motion ID."""
2
+
3
+ import copy
4
+ import hashlib
5
+ import importlib.util
6
+ import json
7
+ from pathlib import Path
8
+ import sqlite3
9
+ import tempfile
10
+ import unittest
11
+
12
+ # The lightweight wire lane has no numerical packages. The mandatory SDK CPU
13
+ # lane installs detector[cpu] and executes all original-source tracking controls.
14
+ _missing = [name for name in ("numpy", "trackers") if importlib.util.find_spec(name) is None]
15
+ if _missing:
16
+ raise unittest.SkipTest("detector[cpu] dependencies absent: " + ", ".join(_missing))
17
+
18
+ from trillboards_detector.actor_tracking import ActorTrackerJournal, TrackingError
19
+ from trillboards_detector.detections import Detection
20
+
21
+ FIXTURE = Path(__file__).parent / "fixtures" / "actor-appearance-original-g326-v1.json"
22
+ MODEL_SHA = "a26d1586786a09529801517061b84fad833ba07992c1881cc417f935c3c9097d"
23
+
24
+
25
+ class OriginalAppearanceTrackingTest(unittest.TestCase):
26
+ @classmethod
27
+ def setUpClass(cls):
28
+ cls.fixture = json.loads(FIXTURE.read_text())
29
+ cls.frames = cls.fixture["frames"]
30
+ cls.controls = cls.fixture["reviewedContinuityControls"]
31
+
32
+ def call(self, tracker, frame, appearance=True):
33
+ kwargs = {"appearance": frame["appearance"]} if appearance else {}
34
+ return tracker.track(
35
+ frame["request"],
36
+ [Detection(**d) for d in frame["detections"]],
37
+ image_sha256=frame["imageSha256"],
38
+ model_hashes=frame["modelHashes"],
39
+ frame_size=frame["frameSize"],
40
+ **kwargs,
41
+ )
42
+
43
+ def replay(self, tracker, frames=None, appearance=True):
44
+ return {f["sourceFrame"]: self.call(tracker, f, appearance) for f in frames or self.frames}
45
+
46
+ @staticmethod
47
+ def control_actor(result, control):
48
+ return next(
49
+ a["actor"] for a in result["actors"] if a["detectionIndex"] == control["detectionIndex"]
50
+ )
51
+
52
+ def test_motion_only_baseline_reproduces_two_reviewed_cross_person_joins(self):
53
+ self.assertEqual(len({c["reviewedPhysicalPerson"] for c in self.controls}), 3)
54
+ with tempfile.TemporaryDirectory() as td:
55
+ tracker = ActorTrackerJournal(Path(td) / "tracks.sqlite", frame_rate=2)
56
+ try:
57
+ results = self.replay(tracker, appearance=False)
58
+ finally:
59
+ tracker.close()
60
+ ids = {self.control_actor(results[c["sourceFrame"]], c)["id"] for c in self.controls}
61
+ self.assertEqual(len(ids), 1)
62
+
63
+ def test_native_appearance_keeps_three_reviewed_people_in_separate_histories(self):
64
+ with tempfile.TemporaryDirectory() as td:
65
+ tracker = ActorTrackerJournal(Path(td) / "tracks.sqlite", frame_rate=2)
66
+ try:
67
+ results = self.replay(tracker)
68
+ finally:
69
+ tracker.close()
70
+ ids = {self.control_actor(results[c["sourceFrame"]], c)["id"] for c in self.controls}
71
+ self.assertEqual(len(ids), 3)
72
+ for result in results.values():
73
+ self.assertEqual(result["modelHashes"]["person_reid_osnet_0277"], MODEL_SHA)
74
+ self.assertEqual(
75
+ result["identityModel"],
76
+ {
77
+ "modelId": "person_reid_osnet_0277",
78
+ "sha256": MODEL_SHA,
79
+ "preprocessing": "osnet_bgr_linear_128x256_raw_fp32_l2_v1",
80
+ },
81
+ )
82
+
83
+ def test_original_retry_and_service_restart_preserve_committed_physical_people(self):
84
+ with tempfile.TemporaryDirectory() as td:
85
+ path = Path(td) / "tracks.sqlite"
86
+ tracker = ActorTrackerJournal(path, frame_rate=2)
87
+ first = self.replay(tracker, self.frames[:28])
88
+ frame = self.frames[27]
89
+ saved = first[frame["sourceFrame"]]
90
+ tracker.close()
91
+ tracker = ActorTrackerJournal(path, frame_rate=2)
92
+ try:
93
+ self.assertEqual(self.call(tracker, frame), saved)
94
+ rest = self.replay(tracker, self.frames[28:])
95
+ finally:
96
+ tracker.close()
97
+ observed = []
98
+ results = {**first, **rest}
99
+ for point in self.fixture["reviewedCallerFrames"]:
100
+ result = results[point["sourceFrame"]]
101
+ observed.append(self.control_actor(result, point)["id"])
102
+ self.assertTrue(observed)
103
+ self.assertEqual(len(set(observed)), 1)
104
+
105
+ def test_foreign_pixels_model_and_invalid_vectors_do_not_commit_a_frame(self):
106
+ frame = next(f for f in self.frames if f["appearance"]["descriptors"])
107
+ for field, value in [
108
+ ("sourceImageSha256", "0" * 64),
109
+ ("modelSha256", "f" * 64),
110
+ ("embedding", [float("nan")] * 256),
111
+ ("embedding", [0.0] * 256),
112
+ ]:
113
+ altered = copy.deepcopy(frame)
114
+ altered["appearance"]["descriptors"][0][field] = value
115
+ with tempfile.TemporaryDirectory() as td:
116
+ tracker = ActorTrackerJournal(Path(td) / "tracks.sqlite", frame_rate=2)
117
+ try:
118
+ with self.assertRaises(TrackingError):
119
+ self.call(tracker, altered)
120
+ self.assertEqual(tracker.retained_frames(frame["request"]["cameraId"]), 0)
121
+ finally:
122
+ tracker.close()
123
+
124
+ def test_model_or_source_change_cannot_reuse_previous_event_identity(self):
125
+ with tempfile.TemporaryDirectory() as td:
126
+ tracker = ActorTrackerJournal(Path(td) / "tracks.sqlite", frame_rate=2)
127
+ try:
128
+ results = self.replay(tracker, self.frames[:28])
129
+ before = results[self.frames[27]["sourceFrame"]]
130
+ frame = copy.deepcopy(self.frames[28])
131
+ frame["request"]["sourceId"] = "f" * 64
132
+ after = self.call(tracker, frame)
133
+ finally:
134
+ tracker.close()
135
+ self.assertNotEqual(before["epoch"], after["epoch"])
136
+ self.assertEqual(after["continuity"], "context_reset")
137
+ self.assertFalse(
138
+ {a["actor"]["id"] for a in before["actors"]}
139
+ & {a["actor"]["id"] for a in after["actors"]}
140
+ )
141
+
142
+ def test_private_motion_receipts_stay_bounded_with_the_tracking_journal(self):
143
+ with tempfile.TemporaryDirectory() as td:
144
+ path = Path(td) / "tracks.sqlite"
145
+ tracker = ActorTrackerJournal(path, frame_rate=2, retained_frames=32)
146
+ try:
147
+ self.replay(tracker)
148
+ self.assertEqual(tracker.retained_frames(self.frames[0]["request"]["cameraId"]), 32)
149
+ finally:
150
+ tracker.close()
151
+ with sqlite3.connect(path) as db:
152
+ count = db.execute("SELECT count(*) FROM actor_motion_frame").fetchone()[0]
153
+ self.assertEqual(count, 32)
154
+
155
+ def test_failed_identity_checkpoint_rolls_back_motion_and_public_history(self):
156
+ with tempfile.TemporaryDirectory() as td:
157
+ path, control = Path(td) / "tracks.sqlite", Path(td) / "control.sqlite"
158
+ tracker = ActorTrackerJournal(path, frame_rate=2)
159
+ try:
160
+ self.replay(tracker, self.frames[:27])
161
+ with sqlite3.connect(control) as snapshot:
162
+ tracker._db.backup(snapshot)
163
+ tracker._db.execute(
164
+ "CREATE TEMP TRIGGER fail_identity_checkpoint "
165
+ "BEFORE UPDATE ON actor_identity_checkpoint "
166
+ "BEGIN SELECT RAISE(ABORT, 'native qualification write failure'); END"
167
+ )
168
+ before_motion = tracker._db.execute(
169
+ "SELECT count(*) FROM actor_motion_frame"
170
+ ).fetchone()[0]
171
+ with self.assertRaises(TrackingError):
172
+ self.call(tracker, self.frames[27])
173
+ self.assertEqual(tracker.retained_frames(self.frames[0]["request"]["cameraId"]), 27)
174
+ self.assertEqual(
175
+ tracker._db.execute("SELECT count(*) FROM actor_motion_frame").fetchone()[0],
176
+ before_motion,
177
+ )
178
+ tracker._db.execute("DROP TRIGGER fail_identity_checkpoint")
179
+ actual = self.call(tracker, self.frames[27])
180
+ finally:
181
+ tracker.close()
182
+ baseline = ActorTrackerJournal(control, frame_rate=2)
183
+ try:
184
+ expected = self.call(baseline, self.frames[27])
185
+ finally:
186
+ baseline.close()
187
+ self.assertEqual(actual, expected)
188
+ restarted = ActorTrackerJournal(path, frame_rate=2)
189
+ try:
190
+ self.assertEqual(self.call(restarted, self.frames[27]), expected)
191
+ finally:
192
+ restarted.close()
193
+
194
+
195
+ if __name__ == "__main__":
196
+ unittest.main()
@@ -0,0 +1,80 @@
1
+ import copy
2
+ import json
3
+ from pathlib import Path
4
+ import unittest
5
+ from trillboards_detector.server import parse_appearance_model, build_appearance_evidence, WireError
6
+ from trillboards_detector.actor_identity import MODEL_ID, MODEL_SHA256, PREPROCESSING
7
+
8
+
9
+ class AppearanceWireContractTest(unittest.TestCase):
10
+ def test_native_appearance_pin_is_explicit_and_optional(self):
11
+ pin = {"modelId": MODEL_ID, "sha256": MODEL_SHA256}
12
+ self.assertEqual(
13
+ parse_appearance_model(json.dumps({"appearance_model": pin}).encode()), pin
14
+ )
15
+ self.assertIsNone(parse_appearance_model(b"{}"))
16
+
17
+ def test_malformed_or_extra_model_authority_is_rejected(self):
18
+ for pin in (
19
+ None,
20
+ [],
21
+ {"modelId": MODEL_ID},
22
+ {"modelId": MODEL_ID, "sha256": None},
23
+ {"modelId": MODEL_ID, "sha256": "not-a-digest"},
24
+ {"modelId": MODEL_ID, "sha256": MODEL_SHA256, "prompt": "trust me"},
25
+ ):
26
+ with self.subTest(pin=pin), self.assertRaises(WireError):
27
+ parse_appearance_model(json.dumps({"appearance_model": pin}).encode())
28
+
29
+ def native_frame(self):
30
+ fixture = Path(__file__).parent / "fixtures" / "actor-appearance-original-g326-v1.json"
31
+ frame = next(
32
+ f for f in json.loads(fixture.read_text())["frames"] if f["appearance"]["descriptors"]
33
+ )
34
+ from trillboards_detector.detections import Detection
35
+
36
+ result = {
37
+ "version": 1,
38
+ "modelId": MODEL_ID,
39
+ "modelSha256": MODEL_SHA256,
40
+ "preprocessing": PREPROCESSING,
41
+ "imageSha256": frame["imageSha256"],
42
+ "frameSize": {"width": frame["frameSize"][0], "height": frame["frameSize"][1]},
43
+ "inferenceMs": 1.0,
44
+ "descriptors": [
45
+ {k: d[k] for k in ("bounds", "inputSha256", "embedding")}
46
+ for d in frame["appearance"]["descriptors"]
47
+ ],
48
+ }
49
+ return frame, [Detection(**d) for d in frame["detections"]], result
50
+
51
+ def test_native_source_descriptors_keep_the_original_detection_ownership(self):
52
+ frame, detections, result = self.native_frame()
53
+ evidence = build_appearance_evidence(
54
+ result, frame["imageSha256"], frame["frameSize"], detections
55
+ )
56
+ self.assertEqual(evidence, frame["appearance"])
57
+
58
+ def test_foreign_native_source_proof_cannot_be_relabelled_as_the_current_frame(self):
59
+ frame, detections, result = self.native_frame()
60
+ for key, value in (
61
+ ("imageSha256", "0" * 64),
62
+ ("modelSha256", "f" * 64),
63
+ ("frameSize", {"width": 1, "height": 1}),
64
+ ("preprocessing", "wrong_rgb_input"),
65
+ ("inferenceMs", True),
66
+ ("descriptors", []),
67
+ ):
68
+ altered = copy.deepcopy(result)
69
+ altered[key] = value
70
+ with self.subTest(key=key), self.assertRaises(ValueError):
71
+ build_appearance_evidence(
72
+ altered, frame["imageSha256"], frame["frameSize"], detections
73
+ )
74
+ result["descriptors"][0]["bounds"][0] += 1
75
+ with self.assertRaises(ValueError):
76
+ build_appearance_evidence(result, frame["imageSha256"], frame["frameSize"], detections)
77
+
78
+
79
+ if __name__ == "__main__":
80
+ unittest.main()
@@ -44,14 +44,16 @@ if HAVE_RUNTIME:
44
44
 
45
45
  @unittest.skipUnless(HAVE_RUNTIME, "onnxruntime/numpy/Pillow are not installed")
46
46
  class TestBuildCatalogue(unittest.TestCase):
47
- def test_pose_path_does_not_inherit_the_detector_only_override(self):
48
- from trillboards_detector.tasks import RTMPOSE_BODY7
47
+ def test_non_box_paths_do_not_inherit_the_detector_only_override(self):
48
+ from trillboards_detector.tasks import RTMPOSE_BODY7, PERSON_APPEARANCE
49
49
  entries = build_catalogue("rfdetr_medium", None, (RFDETR_MEDIUM,),
50
50
  {"HOME": "/h", "TRILLBOARDS_DETECTOR_MODEL": "/bench/person.onnx"},
51
- task_models=(RTMPOSE_BODY7,))
52
- pose = next(e for e in entries if e.name == "rtmpose_m_body7")
53
- self.assertTrue(str(pose.path).endswith("/models/rtmpose_m_body7/model.onnx"))
54
- self.assertNotEqual(str(pose.path), "/bench/person.onnx")
51
+ task_models=(RTMPOSE_BODY7, PERSON_APPEARANCE))
52
+ for contract in (RTMPOSE_BODY7, PERSON_APPEARANCE):
53
+ entry = next(e for e in entries if e.name == contract.model_name)
54
+ self.assertTrue(str(entry.path).endswith("/models/" + contract.model_name + "/model.onnx"))
55
+ self.assertNotEqual(str(entry.path), "/bench/person.onnx")
56
+ self.assertFalse(hasattr(entry.vocabulary, "class_names"))
55
57
 
56
58
  def test_pose_task_uses_its_own_ota_path_without_detection_classes(self):
57
59
  from trillboards_detector.tasks import RTMPOSE_BODY7
@@ -129,7 +131,7 @@ class TestHealthIsOneRead(unittest.TestCase):
129
131
  self.assertEqual(len(calls), 1, "`/health` read the registry twice; it must describe one moment")
130
132
  # And it is still the payload every existing reader parses.
131
133
  self.assertEqual(payload["model"], "rfdetr_medium")
132
- self.assertEqual(sorted(payload["models"]), ["ppe", "rfdetr_medium", "rtmpose_m_body7"])
134
+ self.assertEqual(sorted(payload["models"]), ["person_reid_osnet_0277", "ppe", "rfdetr_medium", "rtmpose_m_body7"])
133
135
  self.assertEqual(payload["resident_models"], [])
134
136
 
135
137
  def test_before_the_first_stat_the_answer_is_loading_and_names_no_reason(self):
@@ -13,5 +13,5 @@ human sets.
13
13
  """
14
14
 
15
15
  BASE_VERSION = "0.2.0"
16
- SOURCE_FINGERPRINT = "2f51129753df"
17
- VERSION = "0.2.0+src.2f51129753df"
16
+ SOURCE_FINGERPRINT = "02d69f63804d"
17
+ VERSION = "0.2.0+src.02d69f63804d"
@@ -0,0 +1,323 @@
1
+ """Appearance-supported person segments; never merge separate motion identities.
2
+
3
+ Original pixel observations are the only updates. Receipt sequence orders the journal;
4
+ frameId, capture time and original image digest bind the actual observation. Ambiguous or contradictory
5
+ links begin a fresh segment, so event history cannot ride through that link.
6
+ """
7
+
8
+ import copy, hashlib, json, math, re
9
+
10
+ _ID = re.compile(r"[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}\Z")
11
+ _SHA = re.compile(r"[a-f0-9]{64}\Z")
12
+ POLICY = {
13
+ "version": 1,
14
+ "maxCosineDistance": 0.3,
15
+ "currentPersonMargin": 0.05,
16
+ "gallerySize": 5,
17
+ "maxAgeMs": 3000,
18
+ "retainedFrames": 64,
19
+ "maxPeople": 256,
20
+ }
21
+
22
+
23
+ def digest(v):
24
+ return hashlib.sha256(
25
+ json.dumps(v, sort_keys=True, separators=(",", ":"), allow_nan=False).encode()
26
+ ).hexdigest()
27
+
28
+
29
+ def finite(v):
30
+ return type(v) in (int, float) and math.isfinite(v)
31
+
32
+
33
+ def vector(v):
34
+ if not isinstance(v, list) or len(v) != 256 or any(not finite(x) for x in v):
35
+ raise ValueError("Invalid native appearance vector")
36
+ norm = math.sqrt(sum(float(x) * float(x) for x in v))
37
+ if not 0.9999 <= norm <= 1.0001:
38
+ raise ValueError("Native appearance vector is not normalized")
39
+ return [float(x) for x in v]
40
+
41
+
42
+ def distance(a, b):
43
+ return max(0.0, min(2.0, 1.0 - sum(x * y for x, y in zip(a, b))))
44
+
45
+
46
+ class ActorIdentitySegments:
47
+ def __init__(self, binding, model_sha256, *, state=None):
48
+ if (
49
+ not isinstance(binding, dict)
50
+ or set(binding) != {"cameraId", "sourceId", "motionEpoch"}
51
+ or any(not isinstance(v, str) or not _ID.fullmatch(v) for v in binding.values())
52
+ or not isinstance(model_sha256, str)
53
+ or not _SHA.fullmatch(model_sha256)
54
+ ):
55
+ raise ValueError("Invalid physical source or appearance model")
56
+ self.binding = copy.deepcopy(binding)
57
+ self.model = model_sha256
58
+ self.contract = {"binding": self.binding, "modelSha256": self.model, "policy": POLICY}
59
+ self.contract_sha = digest(self.contract)
60
+ self.s = {
61
+ "version": 1,
62
+ "contractSha256": self.contract_sha,
63
+ "lastAtMs": None,
64
+ "tracks": {},
65
+ "receipts": {},
66
+ }
67
+ if state is not None:
68
+ value = copy.deepcopy(state)
69
+ saved = value.pop("stateSha256", None)
70
+ if (
71
+ saved != digest(value)
72
+ or value.get("version") != 1
73
+ or value.get("contractSha256") != self.contract_sha
74
+ or set(value) != {"version", "contractSha256", "lastAtMs", "tracks", "receipts"}
75
+ ):
76
+ raise ValueError("Saved physical continuity contract changed")
77
+ if (
78
+ len(value["tracks"]) > POLICY["maxPeople"]
79
+ or len(value["receipts"]) > POLICY["retainedFrames"]
80
+ ):
81
+ raise ValueError("Saved physical continuity exceeds bounds")
82
+ if value["lastAtMs"] is not None and (
83
+ type(value["lastAtMs"]) is not int or value["lastAtMs"] < 0
84
+ ):
85
+ raise ValueError("Invalid saved source clock")
86
+ for key, t in value["tracks"].items():
87
+ if (
88
+ not _ID.fullmatch(key)
89
+ or not 1 <= len(t["gallery"]) <= POLICY["gallerySize"]
90
+ or type(t["lastAtMs"]) is not int
91
+ or t["lastAtMs"] > value["lastAtMs"]
92
+ ):
93
+ raise ValueError("Invalid saved appearance gallery")
94
+ self._actor(t["actor"])
95
+ for g in t["gallery"]:
96
+ vector(g["values"])
97
+ self.s = value
98
+
99
+ def _actor(self, a):
100
+ if (
101
+ not isinstance(a, dict)
102
+ or set(a) != {"kind", "cameraId", "id", "epoch"}
103
+ or a["kind"] != "person"
104
+ or a["cameraId"] != self.binding["cameraId"]
105
+ or a["epoch"] != self.binding["motionEpoch"]
106
+ or not isinstance(a["id"], str)
107
+ or not _ID.fullmatch(a["id"])
108
+ ):
109
+ raise ValueError("Invalid source-bound person identity")
110
+
111
+ def snapshot(self):
112
+ out = copy.deepcopy(self.s)
113
+ out["stateSha256"] = digest(out)
114
+ return out
115
+
116
+ def process(self, f):
117
+ if (
118
+ not isinstance(f, dict)
119
+ or any(f.get(k) != v for k, v in self.binding.items())
120
+ or type(f.get("capturedAtMs")) is not int
121
+ or not 0 <= f["capturedAtMs"] <= 9007199254740991
122
+ or type(f.get("sequence")) is not int
123
+ or f["sequence"] < 0
124
+ or not isinstance(f.get("frameId"), str)
125
+ or not _ID.fullmatch(f["frameId"])
126
+ or not isinstance(f.get("imageSha256"), str)
127
+ or not _SHA.fullmatch(f["imageSha256"])
128
+ ):
129
+ raise ValueError("Invalid original physical frame identity")
130
+ candidates = f.get("candidates")
131
+ if not isinstance(candidates, list) or len(candidates) > POLICY["maxPeople"]:
132
+ raise ValueError("Unbounded physical observations")
133
+ seen = set()
134
+ values = []
135
+ for c in candidates:
136
+ a = c["motionActor"]
137
+ self._actor(a)
138
+ key = a["id"]
139
+ if key in seen:
140
+ raise ValueError("Duplicate native motion person")
141
+ seen.add(key)
142
+ b = c["box"]
143
+ d = c["descriptor"]
144
+ if (
145
+ len(b) != 4
146
+ or any(not finite(x) for x in b)
147
+ or b[0] < 0
148
+ or b[1] < 0
149
+ or b[2] <= b[0]
150
+ or b[3] <= b[1]
151
+ ):
152
+ raise ValueError("Invalid native observed person box")
153
+ if (
154
+ d.get("modelSha256") != self.model
155
+ or d.get("sourceImageSha256") != f["imageSha256"]
156
+ or not isinstance(d.get("inputSha256"), str)
157
+ or not _SHA.fullmatch(d["inputSha256"])
158
+ ):
159
+ raise ValueError("Native appearance source or model changed")
160
+ values.append(vector(d["values"]))
161
+ fingerprint = digest({"contractSha256": self.contract_sha, "frame": f})
162
+ old = self.s["receipts"].get(f["frameId"])
163
+ if old is not None:
164
+ if old["fingerprint"] != fingerprint:
165
+ raise ValueError("Committed original frame changed")
166
+ return copy.deepcopy(old["result"])
167
+ at = f["capturedAtMs"]
168
+ if self.s["lastAtMs"] is not None and at <= self.s["lastAtMs"]:
169
+ raise ValueError("Physical observations must preserve source time")
170
+ tracks = copy.deepcopy(self.s["tracks"])
171
+ ended = []
172
+ actors = []
173
+ for key, t in list(tracks.items()):
174
+ if at - t["lastAtMs"] > POLICY["maxAgeMs"]:
175
+ ended.append(t["actor"])
176
+ del tracks[key]
177
+ for index, c in enumerate(candidates):
178
+ raw = c["motionActor"]
179
+ key = raw["id"]
180
+ v = values[index]
181
+ prior = tracks.get(key)
182
+ cost = None
183
+ other = None
184
+ reason = "new_observation_segment"
185
+ if prior is not None:
186
+ cost = min(distance(v, g["values"]) for g in prior["gallery"])
187
+ other = min(
188
+ (distance(v, x) for j, x in enumerate(values) if j != index), default=None
189
+ )
190
+ if cost > POLICY["maxCosineDistance"]:
191
+ reason = "appearance_changed"
192
+ elif other is not None and other - cost < POLICY["currentPersonMargin"]:
193
+ reason = "appearance_ambiguous"
194
+ else:
195
+ reason = "appearance_supported"
196
+ if reason == "appearance_supported":
197
+ actor = copy.deepcopy(prior["actor"])
198
+ gallery = prior["gallery"]
199
+ else:
200
+ if prior is not None:
201
+ ended.append(prior["actor"])
202
+ actor = {
203
+ "kind": "person",
204
+ "cameraId": self.binding["cameraId"],
205
+ "epoch": self.binding["motionEpoch"],
206
+ "id": "pa_"
207
+ + digest(
208
+ {
209
+ "contractSha256": self.contract_sha,
210
+ "motionActor": raw,
211
+ "firstFrameId": f["frameId"],
212
+ "firstImageSha256": f["imageSha256"],
213
+ }
214
+ )[:32],
215
+ }
216
+ gallery = []
217
+ gallery = (
218
+ gallery
219
+ + [
220
+ {
221
+ "values": v,
222
+ "frameId": f["frameId"],
223
+ "sourceImageSha256": f["imageSha256"],
224
+ "inputSha256": c["descriptor"]["inputSha256"],
225
+ "capturedAtMs": at,
226
+ }
227
+ ]
228
+ )[-POLICY["gallerySize"] :]
229
+ tracks[key] = {"actor": actor, "lastAtMs": at, "gallery": gallery}
230
+ actors.append(
231
+ {
232
+ "motionActor": copy.deepcopy(raw),
233
+ "actor": actor,
234
+ "box": copy.deepcopy(c["box"]),
235
+ "continuity": reason,
236
+ "appearanceDistance": cost,
237
+ "nearestCurrentOtherPersonDistance": other,
238
+ "descriptorModelSha256": self.model,
239
+ "descriptorInputSha256": c["descriptor"]["inputSha256"],
240
+ }
241
+ )
242
+ if len(tracks) > POLICY["maxPeople"]:
243
+ raise ValueError("Physical continuity capacity exhausted")
244
+ result = {
245
+ "version": 1,
246
+ **copy.deepcopy(self.binding),
247
+ "frameId": f["frameId"],
248
+ "sequence": f["sequence"],
249
+ "capturedAtMs": at,
250
+ "imageSha256": f["imageSha256"],
251
+ "contractSha256": self.contract_sha,
252
+ "actors": actors,
253
+ "endedActors": sorted(ended, key=lambda a: a["id"]),
254
+ "qualification": False,
255
+ }
256
+ result["sha256"] = digest(result)
257
+ receipts = copy.deepcopy(self.s["receipts"])
258
+ receipts[f["frameId"]] = {"fingerprint": fingerprint, "result": result}
259
+ while len(receipts) > POLICY["retainedFrames"]:
260
+ del receipts[next(iter(receipts))]
261
+ self.s = {
262
+ "version": 1,
263
+ "contractSha256": self.contract_sha,
264
+ "lastAtMs": at,
265
+ "tracks": tracks,
266
+ "receipts": receipts,
267
+ }
268
+ return copy.deepcopy(result)
269
+
270
+
271
+ MODEL_ID = "person_reid_osnet_0277"
272
+ MODEL_SHA256 = "a26d1586786a09529801517061b84fad833ba07992c1881cc417f935c3c9097d"
273
+ PREPROCESSING = "osnet_bgr_linear_128x256_raw_fp32_l2_v1"
274
+
275
+
276
+ def checked_appearance(value, detections, image_sha256, frame_size):
277
+ """Native descriptor ownership is checked before any tracking state changes."""
278
+ if (
279
+ not isinstance(value, dict)
280
+ or set(value) != {"modelId", "sha256", "preprocessing", "descriptors"}
281
+ or value["modelId"] != MODEL_ID
282
+ or value["sha256"] != MODEL_SHA256
283
+ or value["preprocessing"] != PREPROCESSING
284
+ or not isinstance(value["descriptors"], list)
285
+ ):
286
+ raise ValueError("Invalid pinned native appearance proof")
287
+ wanted = {i for i, d in enumerate(detections) if d["label"] == "person"}
288
+ found = set()
289
+ for d in value["descriptors"]:
290
+ if (
291
+ not isinstance(d, dict)
292
+ or set(d)
293
+ != {
294
+ "detectionIndex",
295
+ "modelSha256",
296
+ "sourceImageSha256",
297
+ "inputSha256",
298
+ "bounds",
299
+ "embedding",
300
+ }
301
+ or type(d["detectionIndex"]) is not int
302
+ or d["detectionIndex"] not in wanted
303
+ or d["detectionIndex"] in found
304
+ or d["modelSha256"] != MODEL_SHA256
305
+ or d["sourceImageSha256"] != image_sha256
306
+ or not isinstance(d["inputSha256"], str)
307
+ or not _SHA.fullmatch(d["inputSha256"])
308
+ ):
309
+ raise ValueError("Native appearance belongs to another observed person or frame")
310
+ box = detections[d["detectionIndex"]]
311
+ expected = [
312
+ math.floor(box["x"]),
313
+ math.floor(box["y"]),
314
+ min(frame_size[0], math.ceil(box["x"] + box["width"])),
315
+ min(frame_size[1], math.ceil(box["y"] + box["height"])),
316
+ ]
317
+ if d["bounds"] != expected:
318
+ raise ValueError("Native appearance crop differs from the observed person")
319
+ vector(d["embedding"])
320
+ found.add(d["detectionIndex"])
321
+ if found != wanted:
322
+ raise ValueError("Native appearance does not cover every detected person")
323
+ return copy.deepcopy(value)