feat(perception): define TrackGeometry v1 contract

This commit is contained in:
DCCONSTRUCTIONS
2026-07-27 11:46:23 +03:00
parent 091d560ac8
commit 10c306f162
5 changed files with 1354 additions and 7 deletions
@@ -142,6 +142,18 @@ real authority.
with zero bbox-centre collateral; the generic geometry point mask is
rejected because it would erase accepted object evidence. Navigation,
safety and command authority remain false.
- [x] Add ADR 0024 and the executable A5 contracts:
`missioncore.track-geometry/v1`,
`missioncore.track-geometry-frame/v1`,
`missioncore.track-geometry-binding/v1` and
`missioncore.point-slab/v1`.
- [x] Enforce camera-owned semantic identity, lossless unique frame-local
source indices, one point owner, explicit current/held/persistent and
current/held/persistent metric bases, retained reason codes, no fake
range/class, no missing-point free-space inference and no runtime authority.
- [x] Verify strict round-trip plus adversarial duplicate ownership, unknown
owner, camera-only/conflict range, geometry-only semantics, held/persistent
ownership, unavailable source and authority mutation cases.
The frozen A3 engineering and human generations cover all 486 items and
retains the exact A2 materialization/review-pack and 42-sheet evidence
@@ -154,13 +166,14 @@ geometry and 21 visible missed class-bearing objects. Earlier generations and
drafts remain historical and are not rewritten or presented as the current
product workflow.
A3 and A4 are complete. E31 accepts only the recorded RAVNOVES00 diagnostic
binding and does not claim that host arrival is hardware firing time. The
factory KB4 identity is exact, but a measured calibration-target residual and
physical body/mount dimensions are unavailable. The accepted profile is
therefore source-session scoped and cannot transfer to another mount. A5
`TrackGeometry v1` is the next critical-path implementation; E32 publication
must bind both that contract and the accepted E31 profile.
A3, A4 and the A5 contract gate are complete. E31 accepts only the recorded
RAVNOVES00 diagnostic binding and does not claim that host arrival is hardware
firing time. The factory KB4 identity is exact, but a measured
calibration-target residual and physical body/mount dimensions are
unavailable. The accepted profile is therefore source-session scoped and
cannot transfer to another mount. A6/E32 full replay is the next critical-path
implementation and must bind every published frame to both `TrackGeometry v1`
and the accepted E31 profile.
### A3 residual and human-exception policy
@@ -0,0 +1,85 @@
# 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