feat(perception): define TrackGeometry v1 contract
This commit is contained in:
@@ -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
|
||||
Reference in New Issue
Block a user