feat: explain local surface residuals

docs/13_LIDAR_WORKER_PRODUCT_AND_ROADMAP.md

@@ -1,10 +1,10 @@
 # LiDAR worker: product value, evidence boundary and implementation roadmap
 
-Date: 2026-07-25
+Date: 2026-07-26
 Status: accepted architecture plan; L0/L1 implemented; L2 diagnostic A/B
-complete; full GOOSE and RELLIS qualification complete; L2.6c K1 replay
-local-surface temporal qualification and operator triage implemented;
-residual explainability and live shadow next
+complete; full GOOSE and RELLIS qualification complete; L2.6d K1 replay
+local-surface temporal qualification, operator triage and prior-plane residual
+explainability implemented; bounded live shadow next
 Scope: passively received real-time K1 point/pose evidence, immutable replay and
 future live shadow processing
 Explicitly out of scope: K1 firmware modification, a new onboard exporter, new
@@ -414,7 +414,7 @@ Dataset expansion is no longer the next gate.
 - [x] Publish a deterministic, read-only operator queue for temporal
   transitions and heavy prediction tails, with source-frame navigation and no
   safety authority.
-- [ ] Preserve the prior prediction plane and point/cell-aligned residual
+- [x] Preserve the prior prediction plane and point/cell-aligned residual
   evidence so a selected tail can be explained spatially instead of only by an
   aggregate p95.
 - [ ] Complete the remaining qualification report with per-frame latency,
@@ -474,8 +474,31 @@ not merely a one-frame numerical spike. Source frames `1253–1254` reach
 surface remains stable. This separates a local prediction-tail problem from a
 global plane-transition problem. The recording has no independent ground truth
 for either episode, so the UI calls them review evidence rather than algorithm
-failures. The next replay slice must retain and display the prior-plane
-cell/point residuals before changing fit thresholds or entering live shadow.
+failures.
+
+The L2.6d derivative
+`k1-local-surface-628cd024775f02fea99765d1fb457efec2d5cc4d7371e56818dfe8e08c9b3b74`
+preserves the exact prior-only plane and signed residual for every evaluated
+lower-cell observation. The frame API exposes this evidence read-only and
+source-aligned; the browser overlays a translucent prior-plane plus enlarged
+in-band, above-plane and below-plane cells over a dimmed source-frame cloud.
+The current frame remains excluded from plane input.
+
+This changes the episode interpretation. Source frame `1254` evaluates `98`
+cells: `36` are above the `0.16 m` prior-band and none are below it. Frame
+`1253` has `31/97` above-band cells and none below. Their above-band centroids
+are approximately `(3.06, 0.95) m` and `(2.46, 0.65) m` from the recorded
+sensor position in map XY. The large tail is therefore a spatially localized,
+positive structure entering the lower-cell evidence, not a symmetric global
+plane wobble. This still does not identify the physical object without
+independent ground truth. Frame `1195` instead has only seven out-of-band cells
+(`5` above, `2` below) while the fitted surface slope and roughness move
+together, preserving its separate interpretation as a surface-regime
+transition.
+
+No fit threshold was changed after this review. The next gate is a bounded
+latest-wins live-shadow queue using the same profile and evidence contract,
+still without commands, free-space, navigation or safety authority.
 
 Exit: one immutable K1 session yields both a persistent reconstruction and a
 bounded local world state without hard-coded terrain height or scanner-side
@@ -563,8 +586,10 @@ covers all available `RAVNOVES00` samples and is visible in the operator
 interface. Leave-current-frame-out temporal qualification now covers `525`
 samples: the median surface error is stable, while the p95 tail remains too
 large for a free-space claim. Deterministic triage has reduced the first manual
-inspection set to four high-priority frames in two episodes. The highest-value
-immediate work is prior-plane residual explainability for those episodes, then
-a bounded live-shadow queue and separate dynamic-observation layer. Nvblox,
+inspection set to four high-priority frames in two episodes. Prior-plane
+residual explainability now shows that episode `09` is a localized positive
+structure rather than symmetric plane drift. The highest-value immediate work
+is therefore a bounded live-shadow queue, followed by a separate
+dynamic-observation layer. Nvblox,
 raw-scan detectors and alternative SLAM remain optional later gates because the
 current report contract does not carry their required ray/timing semantics.

docs/14_LIDAR_DATASET_GATEWAY.md

@@ -54,6 +54,10 @@ Implemented now:
 - deterministic `missioncore.k1-local-surface-review/v1` replay triage:
   `37` attention frames grouped into `21` episodes, with four
   high-priority frames and direct source-frame navigation;
+- point/cell-aligned prediction evidence in
+  `missioncore.k1-local-surface-frame/v2`: the prior-only plane, current
+  lower-cell coordinates, signed residual and derived inlier mask are
+  content-bound and visible as a read-only 3D overlay;
 - a provider-neutral read-only local-surface view in
   **Парк → Диагностика LiDAR**, synchronized to the five existing
   RAVNOVES00 scene selectors and a clickable complete-recording timeline;
@@ -89,8 +93,8 @@ Not implemented:
 - no RELLIS ROS bag admission, continuous synchronized playback or production
   promotion;
 - no ray-cleared free-space or planner-authoritative rolling occupancy map.
-- no point/cell-aligned prior-plane residual overlay yet; aggregate tail
-  evidence is not enough to identify its physical cause.
+- no bounded live-shadow execution of the accepted K1 local-surface profile
+  yet; the residual overlay remains replay-only and non-authoritative.
 
 ## Product surface boundary