NODEDC_MISSION_CORE/docs/adr/0024-track-geometry-and-point-ownership.md

ADR 0024: own camera semantics and frame-local geometry explicitly

Date: 2026-07-27 Status: accepted

Context

E29 proved a camera-first diagnostic fusion shape, E30 froze its engineering audit, and E31 accepted one exact source-time/calibration/self-mask profile. Those results still publish experiment-specific dictionaries. Reusing them directly in E32 would leave several architectural ambiguities:

• whether a semantic class came from camera evidence or geometry;
• whether two tracks can claim the same LiDAR source point;
• whether a range is current, held from an earlier frame or supplied by a persistent model;
• whether camera-only, conflict and unknown states may silently acquire metric geometry;
• whether missing endpoints can be treated as free space.

A universal runtime ontology is not justified. The required boundary is local to the perception product and can remain an executable versioned contract.

Decision

1. Mission Core owns missioncore.track-geometry/v1 as the provider-neutral object geometry contract.
2. TrackGeometrySourceBinding pins every frame to the exact source pack, session, representation capability profile, E31 qualification result, calibration identity, coordinate frame and time basis.
3. Camera tracks alone carry semantic track ID, label and image bbox. Geometry-only products carry no semantic class or camera track ID.
4. Evidence state is explicit and closed: agree, single-source-camera, conflict, unknown or single-source-geometry.
5. Currentness is independent and closed: current, held or persistent. Held values reference an earlier frame and persistent values reference a separate model. Neither owns current source points.
6. Metric basis is explicit: current-points, held-last-current, persistent-model or unavailable.
7. Camera-only, conflict and current unknown states cannot publish a range. Current agree and current geometry-only products require accepted source points and a positive range.
8. missioncore.point-slab/v1 is the sole container for accepted current metric points. Each row retains its lossless frame-local source index, map-frame XYZ and exactly one owner index.
9. Source indices in a slab are unique and bounded by the source-frame point count. This makes double ownership unrepresentable.
10. Candidate, rejected, held and persistent points are not inserted into the current accepted slab. Their reason/provenance remains on the geometry product or a separately bound model.
11. Missing source evidence remains unknown. The contract fixes absence_of_points_means_free=false.
12. TrackGeometry has no command, navigation or safety authority.

Consequences

• E32 can translate E29/E31 evidence into one stable frame contract without changing camera/geometry ownership.
• A duplicate source-point claim, fake range, invented class or current/held conflation fails at construction and deserialization.
• The contract supports future native scans and simulation providers through their own representation and E31-equivalent source binding; it does not upgrade historical K1 evidence.
• PointSlab currently defines the semantic array shape and strict JSON round-trip. E32 may add a digest-bound binary artifact encoding without changing ownership semantics.
• Planner-facing occupancy remains a later A8 product with its own admission; TrackGeometry does not imply free space or traversability.

Implementation

• src/k1link/compute/track_geometry.py
• src/k1link/compute/sensor_representation.py
• tests/test_track_geometry.py
• tests/test_sensor_representation.py
• docs/16_ARCHITECTURE_AUDIT_EXECUTION_ROADMAP.md

References

• ADR 0018: LiDAR evidence before models
• ADR 0021: dataset gateway representation boundary
• ADR 0023: sensor representation capabilities and free-space admission
• LAB E29: camera-first semantics with independent local-surface geometry
• LAB E31: source-time, calibration and self-mask qualification