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