# ADR 0019: preserve LiDAR fields before detector evaluation

Date: 2026-07-25
Status: accepted and implemented

## Context

The accepted E10 LiDAR replay pack v1 is bound to the E10–E26 result line. It
stores camera-selected map XYZ and pose but drops the verified intensity byte,
raw `rgbi`, raw integer coordinates, source header fields and exact host
timestamps. Mutating that schema would invalidate historical evidence while
still leaving detector and scanner-quality assumptions implicit.

Mission Core also needs one operator surface that can distinguish capture
quality from later model quality. A successful worker process or a visually
plausible point cloud is not that evidence.

## Decision

1. Add the separate immutable `missioncore.lidar-replay-pack/v2`; never rewrite
   E10 replay pack v1.
2. Bind each v2 pack to the source raw capture and aligned metadata hashes.
3. Preserve point capture sequence, payload size, exact host epoch and
   monotonic receive times, header seq/stamp/scaler, raw integer XYZ, derived
   map XYZ, raw uint32 `rgbi` and its verified uint8 intensity low byte.
4. Preserve pose messages independently with their source/header/timing,
   position, quaternion, distance and accuracy fields.
5. Hash the canonical logical arrays, not only the compressed NPZ bytes.
6. Re-decode the immutable source and compare all persisted arrays before a
   pack is accepted. Any mismatch fails the pack.
7. Publish a separate hashed scanner-quality report: cadence, density,
   intensity, sequence anomalies and nearest-pose coverage.
8. Expose only path-free, read-only catalog/detail responses to React.
9. Deduplicate superseded producers by logical content identity in the UI.
10. Keep command, navigation and safety authority false.

## Consequences

- PointPillars now has retained XYZI evidence for replay, but remains degraded
  because K1 supplies vendor-mapped increments rather than admitted raw sweeps.
- Scanner/transport timing tails become visible before model tuning.
- Reprocessing can compare new worker/model generations against exactly the
  same point and pose evidence.
- The browser displays qualification facts but never loads raw NPZ payloads or
  runs GPU perception.
- Ring, per-point time, scan geometry and IMU remain explicitly absent.
- Nvblox, LiDAR odometry and LIO/SLAM remain blocked.

## Accepted real evidence

The first accepted real pack was built from
`20260719T220917Z_viewer_live`: 66 point frames, 226,963 points, 70 pose frames,
24 exact array comparisons and zero mismatches. Pose coverage was 100% at the
100 ms host-arrival threshold. Point-frame interval was p50 80.4 ms, p95
186.6 ms and maximum 1,153.4 ms.

## References

- `src/k1link/compute/lidar_replay.py`
- `src/k1link/web/lidar_api.py`
- `apps/control-station/src/workspaces/LidarQualityWorkspace.tsx`
- `docs/13_LIDAR_WORKER_PRODUCT_AND_ROADMAP.md`