# 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
  -> optional validated 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.

## Recorded Rerun projection

Mission Core discovers only results whose validated job names the opened
session. Before projection it revalidates the complete job/result binding,
artifact digests, ordered timestamps and result metrics. It then reconstructs
the exact fMP4 epoch, verifies decoded dimensions/frame count with `ffprobe`,
decodes exactly the admitted number of RGB frames and rejects boxes outside the
image.

The optional `perception.rrd` endpoint returns either HTTP 204 or one complete,
bounded RRF2 stream for the opened Rerun recording ID. The browser never splits
that stream and never replaces the base recording when the optional layer is
absent or rejected. Accepted frames are logged under `/perception/camera` on
the canonical zero-based `session_time` timeline; `Image` and `Boxes2D` rows
therefore seek with the point-cloud archive. Generated overlays are a private,
content-addressed cache and remain rebuildable from the immutable job/result.

In **Наблюдение → Пространственная сцена**, a **Распознавание** button appears
only after the layer has been admitted. It switches the active native Rerun view
between the camera/detections and the point cloud. TEST007's accepted fragment
occupies approximately `01:07.351–01:12.848`; Rerun's latest-at query retains
the last admitted frame after that short fragment.

## 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. Qualify TEST007's 206-second epoch and record throughput/resource telemetry.
2. Replace SSH/SCP with a reviewed authenticated worker transport.
3. Add bounded live queues, sampling/drop policy and acquisition-isolation
   tests.
4. Introduce tracking, segmentation/free-space, calibration and point-cloud
   models as separate versioned pipelines.