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,85 @@
+# External perception worker contract
+
+## Boundary
+
+```text
+K1
+  -> XGRIDS device plugin / Mission Core Edge
+  -> authoritative raw session on Mac
+  -> bounded missioncore.compute-job/v1
+  -> replaceable GPU worker / Triton
+  -> content-addressed missioncore.compute-result/v1
+  -> future optional Rerun derived layer
+```
+
+The GPU worker cannot discover, provision, start or stop a K1. It receives an
+observation package and returns derived observations. The Mac archive is never
+rewritten when a job is prepared or a result is received.
+
+## Recorded camera job v1
+
+`k1link compute prepare-camera-job` accepts a sealed cataloged session, one
+camera source and one physical codec epoch. It performs the canonical camera
+checks before and after copying into a private staging directory:
+
+- summary schema/source/epoch and per-segment durability contract;
+- exact ordered JSONL index and its summary SHA-256;
+- init SHA-256, every segment length/SHA-256 and complete stream SHA-256;
+- continuous ISO-BMFF decode timeline and finite media duration;
+- source session-time mapping through the captured host clock origin.
+
+Publication atomically renames this layout below ignored storage:
+
+```text
+<jobs>/<job-id>/
+├── job.json
+└── input/camera/<source-id>/epoch-N/
+    ├── summary.json
+    ├── index.jsonl
+    ├── init.mp4
+    └── segments/*.m4s
+```
+
+`input_sha256` is SHA-256 over canonical JSON for the complete path-free input
+descriptor. `job_id` includes its first 96 bits and validators require the full
+digest, so a prefix collision fails closed.
+
+## Recorded result v1
+
+The accepted worker profile verifies every transferred file, reconstructs the
+stream outside the job, decodes frames and preserves strictly increasing
+best-effort timestamps in session seconds. Its result identity is canonical JSON
+covering:
+
+- job and full input generation;
+- pipeline ID/version;
+- model ID/version/weight SHA-256;
+- score/NMS thresholds, tensor shape, color order and letterbox policy.
+
+The identity's full SHA-256 names an immutable `result-<sha256>` directory.
+The result manifest binds the detection artifact's length and SHA-256. A repeat
+with the same identity validates the existing directory and returns it without
+calling Triton.
+
+## Accepted model profile
+
+- YOLOX-S official ONNX from upstream release `0.1.1rc0`;
+- Apache-2.0;
+- SHA-256
+  `c5c2d13e59ae883e6af3b45daea64af4833a4951c92d116ec270d9ddbe998063`;
+- FP32 input `[1,3,640,640]`, BGR, bilinear top-left letterbox, pad 114;
+- FP32 output `[1,8400,85]`, official grid/stride decode, COCO-80;
+- Triton 2.70.0 / ONNX Runtime GPU backend in the pinned 26.06 image.
+
+This generic model is useful for proving the contract and timing path. It is not
+accepted for obstacle avoidance, free-space estimation or safety decisions.
+
+## Open gates
+
+1. Import the accepted result as an optional session-timestamped Rerun layer.
+2. Qualify TEST007's 206-second epoch and record throughput/resource telemetry.
+3. Replace SSH/SCP with a reviewed authenticated worker transport.
+4. Add bounded live queues, sampling/drop policy and acquisition-isolation
+   tests.
+5. Introduce tracking, segmentation/free-space, calibration and point-cloud
+   models as separate versioned pipelines.