feat: explain local surface residuals

apps/control-station/test/localSurface.test.mjs

@@ -136,7 +136,7 @@ function catalog(overrides = {}) {
 
 function frame(overrides = {}) {
   return {
-    schema_version: "missioncore.k1-local-surface-frame/v1",
+    schema_version: "missioncore.k1-local-surface-frame/v2",
     model_id: modelId,
     source_pack_id: sourcePackId,
     session_id: "20260720T065719Z_viewer_live",
@@ -161,6 +161,7 @@ function frame(overrides = {}) {
     },
     surface: {
       plane_coefficients_map: [0, 0, 1, 0],
+      local_radius_m: 10,
       sensor_height_m: 1.3,
       slope_deg: 0,
       roughness_m: 0.02,
@@ -179,10 +180,23 @@ function frame(overrides = {}) {
     prediction: {
       available: true,
       current_frame_excluded: true,
-      cell_count: 32,
+      cell_count: 2,
       residual_p50_m: 0.04,
       residual_p95_m: 0.2,
       inlier_fraction: 0.95,
+      evidence: {
+        available: true,
+        basis: "current-lower-cell-observations",
+        coordinate_frame: "map",
+        distance_unit: "m",
+        current_frame_excluded_from_plane: true,
+        surface_inlier_band_m: 0.16,
+        prior_plane_coefficients_map: [0, 0, 1, 0],
+        cell_points_xyz_m: [[0.25, 0.25, 0.02], [1.25, 0.25, 0.18]],
+        cell_signed_residual_m: [0.02, 0.18],
+        cell_inlier: [1, 0],
+        ground_truth: false,
+      },
     },
     temporal: {
       compared: true,
@@ -374,6 +388,9 @@ test("decodes passive local-surface evidence", () => {
   assert.equal(decodedFrame.counts.occupied, 1);
   assert.equal(decodedFrame.counts.stepCandidate, 1);
   assert.equal(decodedFrame.prediction.currentFrameExcluded, true);
+  assert.equal(decodedFrame.prediction.evidence.available, true);
+  assert.equal(decodedFrame.prediction.evidence.cellPointsXyzM.length, 2);
+  assert.deepEqual(decodedFrame.prediction.evidence.cellInlier, [1, 0]);
   assert.equal(decodedFrame.surface.sensorHeightM, 1.3);
 
   const decodedTimeline = parseLidarLocalSurfaceTimeline(timeline());
@@ -413,6 +430,15 @@ test("rejects command authority", () => {
   );
 });
 
+test("rejects forged prediction residual evidence", () => {
+  const forged = frame();
+  forged.prediction.evidence.cell_inlier = [0, 0];
+  assert.throws(
+    () => parseLidarLocalSurfaceFrame(forged),
+    LidarLocalSurfaceContractError,
+  );
+});
+
 test("fetches the complete local-surface timeline read-only", async () => {
   const requests = [];
   const decoded = await fetchLidarLocalSurfaceTimeline(modelId, {