# ADR 0023: require sensor capabilities before algorithm admission

Date: 2026-07-26
Status: accepted

## Context

ADR 0018 introduced the immutable K1-specific
`missioncore.lidar-evidence-profile/v1`, and ADRs 0020–0021 established that the
external K1 `lio_pcl` product is a post-LIO, map-registered increment rather
than a native sensor scan. Those decisions correctly block known incompatible
LiDAR stages, but the compatibility rules are still encoded per stage.

Mission Core must also admit future native scanners, depth sources and
simulation providers without allowing an algorithm to infer missing physical
properties from a successful API call. In particular, the absence of endpoints
in the current K1 representation is not evidence that a ray traversed free
space.

## Decision

1. Mission Core owns
   `missioncore.sensor-representation-capabilities/v1` as a provider-neutral
   description of the physical properties admitted for one versioned source
   representation.
2. The existing LiDAR evidence profile remains immutable. The capability
   profile references it by `source_profile_id`; it does not replace or rewrite
   source evidence.
3. K1 `lio_pcl` is represented as `registered-map-increment` with
   `frame-increment` currentness. It admits metric XYZ, metric intensity,
   map registration and a separate sensor pose.
4. K1 `lio_pcl` does not admit per-point time, ring/channel, a separate IMU,
   a shared hardware clock, a native ray model, per-point ray origin, motion
   compensation, ray clearing, free-space evidence or persistent
   reconstruction.
5. Algorithms own a versioned requirements document with accepted
   representation kinds and required capabilities.
6. Admission is binary and fail-closed. A missing capability or incompatible
   representation rejects the algorithm/input pairing; Mission Core never
   synthesizes a capability to make an integration run.
7. Successful compatibility admission does not grant command, navigation or
   safety authority.
8. `absence_of_endpoints_means_free` is fixed to `false`, and unknown remains
   unknown. Planner adapters must separately require accepted free-space
   evidence.

## Consequences

- Endpoint-only occupied marking can consume the K1 registered increment.
- Projective free-space mappers, ray clearing, TSDF/ESDF integrations and
  native-scan algorithms reject the K1 profile until a different admitted
  source supplies their requirements.
- A future native MID-360 export or synthetic scan receives a separate source
  and capability profile; it does not upgrade historical K1 recordings.
- Capability compatibility can be used by workers, provider adapters and LAB
  manifests without moving product ownership into ROS 2.
- Track geometry and local occupied/unknown contracts can bind the exact
  representation profile and preserve the same fail-closed semantics.

## Implementation

- `src/k1link/compute/sensor_representation.py`
- `src/k1link/compute/e30_review_pack.py`
- `src/k1link/compute/e30_materialization.py`
- `src/k1link/web/e30_review_api.py`
- `apps/control-station/src/core/laboratory/e30Review.ts`
- `apps/control-station/src/workspaces/E30ReviewWorkspace.tsx`
- `tests/test_sensor_representation.py`
- `tests/test_e30_review_pack.py`
- `tests/test_e30_materialization.py`
- `apps/control-station/test/e30Review.test.mjs`
- `docs/16_ARCHITECTURE_AUDIT_EXECUTION_ROADMAP.md`

## References

- ADR 0018: LiDAR evidence before models
- ADR 0020: Patchwork++ vendor-map boundary
- ADR 0021: native scan, normalized scan and rolling-map separation
- `docs/13_LIDAR_WORKER_PRODUCT_AND_ROADMAP.md`