docs(perception): record external worker acceptance

2026-07-19 16:46:39 +03:00
parent 648d5bced4
commit 31fc4f6567
5 changed files with 254 additions and 0 deletions
@@ -0,0 +1,73 @@
+# ADR 0014: Bounded external perception worker
+
+## Status
+
+Accepted for recorded laboratory execution on 2026-07-19. Live transport and
+behavior integration are not accepted.
+
+## Context
+
+Mission Core has a canonical K1 control/archive path and a second workstation
+with an RTX 4090. Sending the entire K1 archive to an ad hoc model environment,
+letting the GPU host connect to K1 or installing another monolithic Mission Core
+would erase the product boundary already established around the device plugin.
+
+The first useful hypothesis is narrower: can one sealed observation be sent to
+a replaceable executor, processed by a standard model server and returned as a
+versioned derived observation with enough identity to reproduce and reject
+stale results?
+
+## Decision
+
+1. Mission Core Edge on the Mac remains the sole K1 command owner and
+   authoritative raw archive owner.
+2. The edge publishes a bounded `missioncore.compute-job/v1`. The first profile
+   contains one canonical camera codec epoch, its archive index/summary and a
+   path-free manifest; it never contains the full MQTT capture.
+3. The input generation SHA-256 covers session/source identity, media contract,
+   timeline, ordered file identities and byte counts. The job directory name is
+   derived from that generation and publication is atomic.
+4. Camera packaging uses the saved-session `RecordedMediaInspector` timing and
+   digest contract. It additionally verifies summary-level index and complete
+   stream digests before handoff.
+5. The Windows worker is an executor, not a second Mission Core. It revalidates
+   every staged file, decodes a derived copy and cannot talk to K1.
+6. NVIDIA Triton is the first replaceable inference runtime. YOLOX-S is the
+   first generic detector because its official repository/deployment path is
+   Apache-2.0 and an official ONNX artifact can be pinned by SHA-256. Model
+   weights stay outside Git.
+7. A result identity covers the full input generation, pipeline, model digest
+   and parameters. `missioncore.compute-result/v1` plus its detection artifact
+   is atomically published under `result-<identity-sha256>`. Exact repeats
+   validate and return the existing generation without inference.
+8. Detections are observations only. They cannot emit scanner, motion or mission
+   commands.
+9. SSH/SCP is permitted for the recorded lab bootstrap only. Direct Triton or a
+   later routed transport must receive its own address, authentication, bounded
+   queue and failure-policy review before live use.
+
+## Accepted evidence
+
+TEST007 left epoch 1 produced job
+`recorded-camera-fae25b92ecf645c2c9765dd4`. All 59 transferred files and
+4,567,569 package bytes were verified. The worker reconstructed the canonical
+4,549,458-byte H.264 stream with SHA-256
+`bceca577f762fdb79c4e8901e5c2a2330fd07d24dc091b1b703c5af4010d8a56`
+and decoded 56 frames over 5.497 seconds.
+
+Pinned YOLOX-S produced the accepted result
+`result-5484a72e81192b19f4e1da2a2dcfd10c876c277ff3e96c6d60cbc9d917b9f604`.
+It contains 56 generic `person` detections over 54 frames. Mean client-observed
+Triton request latency was 15.611 ms and p95 was 23.728 ms. The result is not a
+quality acceptance for navigation.
+
+## Consequences
+
+- Model/runtime changes can be compared against the same immutable input.
+- The worker can later move from the lab LAN to a routed host without changing
+  K1 ownership.
+- Storage temporarily duplicates the bounded encoded stream and preprocessed
+  frames on the worker; retention remains unimplemented.
+- Host-arrival camera timing does not become sensor calibration.
+- The next accepted vertical must project this result into the saved Rerun
+  timeline before live fan-out is introduced.