feat(perception): qualify lossless lidar observations

2026-07-30 11:37:57 +03:00
parent e56fa0c074
commit 7d1a70d8e0
13 changed files with 1874 additions and 119 deletions
@@ -0,0 +1,91 @@
+# ADR 0034: Lossless replay and diagnostic observation boundary
+
+Date: 2026-07-30
+Status: accepted and implemented
+
+## Decision
+
+The accepted K1 local-surface algorithm consumes one normalized, read-only
+source view. Two immutable source schemas are admitted:
+
+- camera-aligned `missioncore.e10-lidar-replay-pack/v1`;
+- native-cadence, field-retaining `missioncore.lidar-replay-pack/v2`.
+
+The normalized view carries exact source pack identity, artifact SHA-256,
+session identity, representation, schema, native point offsets, map-frame XYZ,
+host-monotonic timing and nearest-pose age. A replay-pack-v2 source additionally
+retains RGBI/intensity provenance. The derivative never rewrites or disguises
+one source as the other.
+
+The lossless v2 builder uses two bounded passes over raw capture evidence. The
+first pass freezes frame counts and scalar header/timing contracts. The second
+pass preallocates and fills numeric arrays one decoded frame at a time, failing
+closed if the source differs between passes. The strict reader decompresses
+each NPZ member once before repeated integrity, field and logical-content
+validation. Repeated on-demand decompression inside a frame loop is forbidden.
+
+## Diagnostic observation derivative
+
+E51 is separate from the persistent reconstruction and the E34 short-TTL
+occupied/unknown layer. It may publish:
+
+- temporal motion candidates derived from a bounded centroid history;
+- current near-occupied proximity candidates from admitted E32 range;
+- camera-owned semantics and semantic provenance;
+- explicit current/held freshness and evidence conflict.
+
+It may not publish:
+
+- a dynamic object class;
+- a collision state;
+- free space from missing points;
+- numeric semantic confidence when the upstream contract has none;
+- command, navigation or safety authority.
+
+A map-frame jump candidate rejects motion publication. Held evidence cannot
+publish current proximity. Collision remains unavailable until the physical
+vehicle body and LiDAR mount/extrinsic geometry are separately bound and
+qualified.
+
+## Resource boundary
+
+All full-session Mac execution is sequential. The current 14-inch 2023 MacBook
+Pro has 18 GiB RAM; replay build, strict validation, local-surface build and
+test execution are never intentionally overlapped. Docker is not part of this
+path. Port `8000` remains the canonical running Mission Core service.
+
+## Accepted evidence
+
+Full native replay:
+
+```text
+lidar-replay-pack-8fc0fb418578b8ee2ac88d502d2acbc63ae533437a9da14f1a9f9d8916f613ce
+```
+
+- 4,570 LiDAR frames;
+- 4,598 pose frames;
+- 10,751,258 points;
+- exact live/replay equivalence passed;
+- pose coverage 100%.
+
+Full v2 local surface:
+
+```text
+k1-local-surface-61a0307497b1e9b32d5521f59aa853bce22d81def7ca4d3fc81273a4162e6d22
+```
+
+- 4,570/4,570 valid;
+- zero stale-pose, insufficient-surface or fit-failure frames;
+- pose-binding age 20.6421 ms p95.
+
+E51:
+
+```text
+e51-motion-semantic-1abb7eb9940608fc5af95a1f318cadfbc42ac2412a8662b6622e000e03da1555
+```
+
+- 4,489/4,489 frames;
+- 2,119,302/2,119,302 current occupied point rows preserved;
+- 0.4148 ms frame-processing p95;
+- 0.2969 MiB process peak-RSS growth;
+- all acceptance checks passed.