fix(sensing-server): unstick empty-room field-model calibration deadlock

POST /api/v1/calibration/start created the FieldModel in Uncalibrated, but
field_bridge::maybe_feed_calibration only fed frames while already Collecting
— and the only thing that sets Collecting is feed_calibration on its first
fed frame. The two gates deadlocked: no first frame was ever fed, so
calibration_frame_count stayed 0 and status never left Uncalibrated. Observed
live on a streaming ESP32 node as {"status":"Uncalibrated","frame_count":0}
that never advanced.

- field_bridge::maybe_feed_calibration: feed while Uncalibrated | Collecting
  so the first frame flips the model to Collecting and the count advances.
- calibration_stop: return structured {success:false, frame_count,
  frames_needed} instead of an opaque 500 when finalized with too few frames.
- FieldModel::min_calibration_frames() accessor for the guard above.
- Regression test: maybe_feed_calibration_advances_uncalibrated_to_collecting.

Presence/motion/vitals were unaffected (separate auto rolling baseline).

Co-Authored-By: claude-flow <ruv@ruv.net>

v2/crates/wifi-densepose-sensing-server/src/field_bridge.rs

@@ -99,10 +99,17 @@ pub fn occupancy_or_fallback(
 
 /// Feed the latest frame to the FieldModel during calibration collection.
 ///
-/// Only acts when the model status is `Collecting`. Wraps the latest frame
-/// as a single-link observation (n_links=1) and feeds it.
+/// Acts while the model is `Uncalibrated` or `Collecting`. The first fed frame
+/// flips a freshly-started (`Uncalibrated`) model to `Collecting` inside
+/// `feed_calibration`; without accepting the `Uncalibrated` state here the two
+/// gates deadlock and the frame count never leaves 0 (calibration/start yields
+/// an `Uncalibrated` model that nothing would ever advance). Wraps the latest
+/// frame as a single-link observation (n_links=1) and feeds it.
 pub fn maybe_feed_calibration(field: &mut FieldModel, frame_history: &VecDeque<Vec<f64>>) {
-    if field.status() != CalibrationStatus::Collecting {
+    if !matches!(
+        field.status(),
+        CalibrationStatus::Uncalibrated | CalibrationStatus::Collecting
+    ) {
         return;
     }
     if let Some(latest) = frame_history.back() {
@@ -180,4 +187,37 @@ mod tests {
         assert_eq!(positions.len(), 1);
         assert_eq!(positions[0], [3.0, 4.0, 5.0]);
     }
+
+    /// Regression: a freshly-started (`Uncalibrated`) field model must begin
+    /// collecting once frames arrive. Before the fix, `maybe_feed_calibration`
+    /// only fed while already `Collecting`, but only `feed_calibration` sets
+    /// `Collecting` — so the first frame was never fed and the count stayed 0.
+    #[test]
+    fn maybe_feed_calibration_advances_uncalibrated_to_collecting() {
+        let mut field = FieldModel::new(single_link_config()).expect("field model");
+        assert_eq!(field.status(), CalibrationStatus::Uncalibrated);
+        assert_eq!(field.calibration_frame_count(), 0);
+
+        // n_subcarriers defaults to 56; one single-link frame of that width.
+        let frame = vec![0.5_f64; 56];
+        let mut history: VecDeque<Vec<f64>> = VecDeque::new();
+        history.push_back(frame);
+
+        maybe_feed_calibration(&mut field, &history);
+
+        assert_eq!(
+            field.status(),
+            CalibrationStatus::Collecting,
+            "first frame must flip Uncalibrated -> Collecting"
+        );
+        assert_eq!(
+            field.calibration_frame_count(),
+            1,
+            "frame count must advance past 0"
+        );
+
+        // Subsequent frames keep accumulating while Collecting.
+        maybe_feed_calibration(&mut field, &history);
+        assert_eq!(field.calibration_frame_count(), 2);
+    }
 }

v2/crates/wifi-densepose-sensing-server/src/main.rs

@@ -4991,6 +4991,20 @@ async fn calibration_start(State(state): State<SharedState>) -> Json<serde_json:
 async fn calibration_stop(State(state): State<SharedState>) -> Json<serde_json::Value> {
     let mut s = state.write().await;
     if let Some(ref mut fm) = s.field_model {
+        // Guard: finalizing before enough empty-room frames have accumulated
+        // is a client-side sequencing error, not a server fault. Return a
+        // clear, structured message (with progress) instead of a 500 so the
+        // caller knows to keep the room empty and poll /calibration/status.
+        let have = fm.calibration_frame_count();
+        let need = fm.min_calibration_frames() as u64;
+        if have < need {
+            return Json(serde_json::json!({
+                "success": false,
+                "error": "Not enough calibration frames yet — keep the room empty and poll /calibration/status until frame_count reaches the target.",
+                "frame_count": have,
+                "frames_needed": need,
+            }));
+        }
         let ts = chrono::Utc::now().timestamp_micros() as u64;
         match fm.finalize_calibration(ts, 0) {
             Ok(modes) => {

v2/crates/wifi-densepose-signal/src/ruvsense/field_model.rs

@@ -449,6 +449,11 @@ impl FieldModel {
             .map_or(0, |ls| ls.observation_count())
     }
 
+    /// Minimum frames required before `finalize_calibration` will succeed.
+    pub fn min_calibration_frames(&self) -> usize {
+        self.config.min_calibration_frames
+    }
+
     /// Feed a calibration frame (one CSI observation per link during empty room).
     ///
     /// `observations` is `[n_links][n_subcarriers]` amplitude data.