86 lines
3.9 KiB
Markdown
86 lines
3.9 KiB
Markdown
# 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
|