[AZ-643] [AZ-665] [AZ-672] mavlink+mapobjects+vlm batch 4

AZ-643 mavlink_layer:
- ack demux on COMMAND_LONG/COMMAND_ACK with oneshot dispatch and
  configurable deadline; MavlinkHandle::send_command + SendCommandError
- MAVLink-2 signing: Signer/Verifier built on SHA-256, key + timestamp
  source, incompat-flag wiring in encoder, reject + counter in decoder
- new tests: tests/ack_demux.rs (3) + tests/signing.rs (5)

AZ-665 mapobjects_store:
- internal/h3_index.rs (h3o wrapper, cell_of, grid_disk, haversine)
- internal/store.rs (in-memory (cell -> Vec<MapObject>) hashmap with
  k-ring classify and class-group resolution)
- public API: MapObjectsStoreHandle::classify(ClassifyInput) ->
  Classification {New|Moved|Existing}
- AC1-4 in tests/classify.rs; AC5 perf gate (#[ignore], passes in
  --release)

AZ-672 vlm_client + autopilot:
- DisabledVlmProvider in shared::contracts; VlmProvider::name() for
  composition-root diagnostics
- vlm_client::VlmClient gated behind feature = "vlm"; placeholder
  until AZ-673 lands the real NanoLLM IPC
- autopilot: vlm_client is now optional = true under feature vlm;
  Runtime::select_vlm_provider picks DisabledVlmProvider when feature
  off OR config.vlm.enabled = false

Workspace deps: +sha2 (mavlink signing), +h3o (mapobjects index).
Batch report: _docs/03_implementation/batch_04_cycle1_report.md

Co-authored-by: Cursor <cursoragent@cursor.com>

crates/mapobjects_store/src/internal/h3_index.rs

@@ -0,0 +1,97 @@
+//! Thin wrapper around `h3o`. Centralises the H3 binding so callers in
+//! `store.rs` (and future engine plug-ins) do not have to know about the
+//! upstream crate's enum types.
+
+use std::collections::HashSet;
+
+use h3o::{CellIndex, LatLng, Resolution};
+use shared::error::{AutopilotError, Result};
+
+/// Default fine resolution per `data_model.md §H3` (~15 m edge length).
+pub const DEFAULT_RESOLUTION: u8 = 10;
+
+/// Default k-ring radius for boundary-safe lookups.
+pub const DEFAULT_K_RING: u32 = 2;
+
+/// Compute the H3 cell that contains `(lat, lon)` at the requested resolution.
+pub fn cell_of(lat: f64, lon: f64, resolution: u8) -> Result<CellIndex> {
+    let res = Resolution::try_from(resolution).map_err(|e| {
+        AutopilotError::Validation(format!("invalid H3 resolution {resolution}: {e}"))
+    })?;
+    let ll = LatLng::new(lat, lon)
+        .map_err(|e| AutopilotError::Validation(format!("invalid lat/lon ({lat}, {lon}): {e}")))?;
+    Ok(ll.to_cell(res))
+}
+
+/// Return the deduplicated set of cells in the k-ring around `cell`.
+///
+/// `h3o::CellIndex::grid_disk` already handles pentagon/edge cases; we just
+/// collect the iterator into a `HashSet` so callers can iterate once.
+pub fn grid_disk(cell: CellIndex, k: u32) -> HashSet<CellIndex> {
+    cell.grid_disk::<HashSet<CellIndex>>(k)
+}
+
+/// Haversine great-circle distance between two GPS points, in metres.
+///
+/// We do all distance math in WGS-84 great-circle space (not in H3 grid
+/// units) because the spec is metric: `distance_threshold_m`,
+/// `move_threshold_m`. H3 cells only narrow the candidate set; the
+/// final accept/reject is by haversine metres.
+pub fn haversine_m(lat1: f64, lon1: f64, lat2: f64, lon2: f64) -> f64 {
+    const EARTH_RADIUS_M: f64 = 6_371_000.0;
+    let to_rad = std::f64::consts::PI / 180.0;
+    let dlat = (lat2 - lat1) * to_rad;
+    let dlon = (lon2 - lon1) * to_rad;
+    let a = (dlat / 2.0).sin().powi(2)
+        + lat1.to_radians().cos() * lat2.to_radians().cos() * (dlon / 2.0).sin().powi(2);
+    let c = 2.0 * a.sqrt().asin();
+    EARTH_RADIUS_M * c
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn cell_of_rejects_bad_resolution() {
+        // Act
+        let err = cell_of(0.0, 0.0, 99).unwrap_err();
+        // Assert
+        assert!(matches!(err, AutopilotError::Validation(_)));
+    }
+
+    #[test]
+    fn cell_of_rejects_nan_latlon() {
+        // Act
+        let err = cell_of(f64::NAN, 0.0, 10).unwrap_err();
+        // Assert — h3o::LatLng::new rejects non-finite values.
+        assert!(matches!(err, AutopilotError::Validation(_)));
+    }
+
+    #[test]
+    fn grid_disk_contains_origin() {
+        // Arrange
+        let cell = cell_of(50.45, 30.52, 10).unwrap();
+        // Act
+        let ring = grid_disk(cell, 2);
+        // Assert
+        assert!(ring.contains(&cell));
+        // k=2 on a non-pentagon should yield 1 + 6 + 12 = 19 cells.
+        assert_eq!(ring.len(), 19);
+    }
+
+    #[test]
+    fn haversine_is_zero_for_same_point() {
+        // Assert
+        assert!(haversine_m(50.45, 30.52, 50.45, 30.52) < 1e-6);
+    }
+
+    #[test]
+    fn haversine_matches_known_distance() {
+        // Arrange — 1 degree of latitude ≈ 111 km along a meridian
+        // Act
+        let d = haversine_m(0.0, 0.0, 1.0, 0.0);
+        // Assert
+        assert!((d - 111_195.0).abs() < 1_000.0, "got {d} m");
+    }
+}

crates/mapobjects_store/src/internal/mod.rs

@@ -0,0 +1,4 @@
+//! Internal-only modules. Not part of the public `mapobjects_store` API.
+
+pub mod h3_index;
+pub mod store;

crates/mapobjects_store/src/internal/store.rs

@@ -0,0 +1,320 @@
+//! In-memory hashmap of known map objects, keyed by H3 cell.
+//!
+//! Classification logic (NEW / MOVED / EXISTING) lives here. Per
+//! `architecture.md §7.12` the on-device map keeps the full per-mission
+//! state in memory; persistence (AZ-668) lands later.
+//!
+//! Concurrency: this module is intentionally single-threaded and not
+//! `Sync`. The public `MapObjectsStoreHandle` wraps it in an `Arc<Mutex<…>>`
+//! so the lock surface is a single owned mutex instead of fine-grained
+//! per-cell locking. With p99 ≤ 1 ms and detection rates < 30 Hz the
+//! single mutex is comfortably within budget.
+
+use std::collections::HashMap;
+
+use chrono::{DateTime, Utc};
+use h3o::CellIndex;
+use shared::error::Result;
+use uuid::Uuid;
+
+use super::h3_index::{cell_of, grid_disk, haversine_m, DEFAULT_K_RING, DEFAULT_RESOLUTION};
+
+/// Per-detection input to `classify`. This bundles the georeferenced
+/// payload the architecture-level "detection" carries (gps, class, conf,
+/// size — see `system-flows.md §F7`) without forcing the shared
+/// `Detection` model to grow geolocation fields. `scan_controller` builds
+/// this from `Detection` + GPS / MGRS context at the call site.
+#[derive(Debug, Clone)]
+pub struct ClassifyInput {
+    pub gps_lat: f64,
+    pub gps_lon: f64,
+    pub mgrs: String,
+    pub class: String,
+    pub size_width_m: f32,
+    pub size_length_m: f32,
+    pub confidence: f32,
+    pub mission_id: String,
+    pub observed_at: DateTime<Utc>,
+}
+
+/// Configuration for the spatial-index + classification policy.
+#[derive(Debug, Clone)]
+pub struct MapObjectsStoreConfig {
+    /// H3 cell resolution. Default 10 (~15 m edge).
+    pub h3_resolution: u8,
+    /// K-ring radius for boundary-safe lookups. Default 2.
+    pub k_ring: u32,
+    /// Maximum distance (m) between input and stored object for the pair
+    /// to be considered a possible match. Beyond this → `NEW`.
+    pub distance_threshold_m: f64,
+    /// Above this delta (m) between input position and the matched
+    /// object's stored position, classification flips to `MOVED`.
+    pub move_threshold_m: f64,
+    /// Class-similarity groups. Each inner vec is one group; classes in
+    /// the same group are considered equivalent for matching (e.g.
+    /// `tree` and `shrub` collapsed). A class not listed in any group
+    /// is its own group of one.
+    pub similar_classes: Vec<Vec<String>>,
+}
+
+impl Default for MapObjectsStoreConfig {
+    fn default() -> Self {
+        Self {
+            h3_resolution: DEFAULT_RESOLUTION,
+            k_ring: DEFAULT_K_RING,
+            // Defaults follow `system-flows.md §F7` (distance 50 m,
+            // move 10 m). The task brief lists different per-AC values
+            // (30 m / 50 m) — callers override per scenario.
+            distance_threshold_m: 50.0,
+            move_threshold_m: 10.0,
+            similar_classes: Vec::new(),
+        }
+    }
+}
+
+/// Outcome of `MapObjectsStore::classify`.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Classification {
+    New {
+        id: Uuid,
+    },
+    Moved {
+        id: Uuid,
+        from_mgrs: String,
+        to_mgrs: String,
+    },
+    Existing {
+        id: Uuid,
+    },
+    /// Reserved for AZ-666 end-of-pass sweep.
+    RemovedCandidate {
+        id: Uuid,
+    },
+    /// Reserved for AZ-666 ignored-suppression.
+    Ignored,
+}
+
+/// Stored shape. Fields beyond what `classify` reads are kept for the
+/// next batch in the same component (AZ-666 ignored-suppression / sweep,
+/// AZ-667 hydrate / dump_pending) which will surface them via the engine
+/// API. The lint allow is scoped to those forward-use fields.
+#[allow(dead_code)]
+#[derive(Debug, Clone)]
+struct StoredMapObject {
+    id: Uuid,
+    h3_cell: CellIndex,
+    mgrs: String,
+    class: String,
+    class_group: String,
+    gps_lat: f64,
+    gps_lon: f64,
+    size_width_m: f32,
+    size_length_m: f32,
+    confidence: f32,
+    first_seen: DateTime<Utc>,
+    last_seen: DateTime<Utc>,
+    mission_id: String,
+}
+
+/// In-memory spatial index of known map objects.
+pub struct Store {
+    config: MapObjectsStoreConfig,
+    by_cell: HashMap<CellIndex, Vec<StoredMapObject>>,
+    /// Total object count, maintained alongside `by_cell` for O(1) metrics.
+    len: usize,
+}
+
+impl Store {
+    pub fn new(config: MapObjectsStoreConfig) -> Self {
+        Self {
+            config,
+            by_cell: HashMap::new(),
+            len: 0,
+        }
+    }
+
+    pub fn len(&self) -> usize {
+        self.len
+    }
+
+    /// Exposed for AZ-666/AZ-667 engine plug-points (`internal::engine::*`).
+    #[allow(dead_code)]
+    pub fn config(&self) -> &MapObjectsStoreConfig {
+        &self.config
+    }
+
+    /// Resolve a raw class string to its canonical group key.
+    ///
+    /// The first class listed in a `similar_classes` group is the group
+    /// key. A class absent from all groups is its own group.
+    fn group_key(&self, class: &str) -> String {
+        for group in &self.config.similar_classes {
+            if group.iter().any(|c| c == class) {
+                // group[0] is guaranteed by Vec invariants once we filter
+                // empty groups out (see new). But be defensive.
+                if let Some(first) = group.first() {
+                    return first.clone();
+                }
+            }
+        }
+        class.to_string()
+    }
+
+    /// Classify a single detection input. Mutates the store on `New` /
+    /// `Moved` / `Existing` (insert / position-update / last_seen-update
+    /// respectively). Returns the classification.
+    pub fn classify(&mut self, input: ClassifyInput) -> Result<Classification> {
+        let query_cell = cell_of(input.gps_lat, input.gps_lon, self.config.h3_resolution)?;
+        let group = self.group_key(&input.class);
+
+        // Find the nearest matching object across the k-ring.
+        let mut best: Option<(CellIndex, usize, f64)> = None;
+        let disk = grid_disk(query_cell, self.config.k_ring);
+        for cell in &disk {
+            if let Some(objects) = self.by_cell.get(cell) {
+                for (idx, obj) in objects.iter().enumerate() {
+                    if obj.class_group != group {
+                        continue;
+                    }
+                    let d = haversine_m(input.gps_lat, input.gps_lon, obj.gps_lat, obj.gps_lon);
+                    if d > self.config.distance_threshold_m {
+                        continue;
+                    }
+                    if best.is_none_or(|(_, _, prev_d)| d < prev_d) {
+                        best = Some((*cell, idx, d));
+                    }
+                }
+            }
+        }
+
+        match best {
+            Some((cell, idx, delta_m)) if delta_m >= self.config.move_threshold_m => {
+                // MOVED — update stored position to the new observation.
+                let bucket = self
+                    .by_cell
+                    .get_mut(&cell)
+                    .expect("cell present during best-match scan");
+                let obj = &mut bucket[idx];
+                let from_mgrs = obj.mgrs.clone();
+                let id = obj.id;
+                obj.gps_lat = input.gps_lat;
+                obj.gps_lon = input.gps_lon;
+                obj.mgrs = input.mgrs.clone();
+                obj.last_seen = input.observed_at;
+                obj.confidence = input.confidence;
+
+                // If the new GPS sits in a different H3 cell, re-bucket.
+                if cell != query_cell {
+                    let moved = bucket.remove(idx);
+                    if bucket.is_empty() {
+                        self.by_cell.remove(&cell);
+                    }
+                    self.by_cell
+                        .entry(query_cell)
+                        .or_default()
+                        .push(StoredMapObject {
+                            h3_cell: query_cell,
+                            ..moved
+                        });
+                }
+                Ok(Classification::Moved {
+                    id,
+                    from_mgrs,
+                    to_mgrs: input.mgrs,
+                })
+            }
+            Some((cell, idx, _)) => {
+                // EXISTING — just refresh last_seen.
+                let bucket = self
+                    .by_cell
+                    .get_mut(&cell)
+                    .expect("cell present during best-match scan");
+                let obj = &mut bucket[idx];
+                obj.last_seen = input.observed_at;
+                Ok(Classification::Existing { id: obj.id })
+            }
+            None => {
+                // NEW — insert.
+                let id = Uuid::new_v4();
+                let stored = StoredMapObject {
+                    id,
+                    h3_cell: query_cell,
+                    mgrs: input.mgrs.clone(),
+                    class: input.class.clone(),
+                    class_group: group,
+                    gps_lat: input.gps_lat,
+                    gps_lon: input.gps_lon,
+                    size_width_m: input.size_width_m,
+                    size_length_m: input.size_length_m,
+                    confidence: input.confidence,
+                    first_seen: input.observed_at,
+                    last_seen: input.observed_at,
+                    mission_id: input.mission_id.clone(),
+                };
+                self.by_cell.entry(query_cell).or_default().push(stored);
+                self.len += 1;
+                Ok(Classification::New { id })
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn input(lat: f64, lon: f64, class: &str) -> ClassifyInput {
+        ClassifyInput {
+            gps_lat: lat,
+            gps_lon: lon,
+            mgrs: format!("MGRS({lat},{lon})"),
+            class: class.into(),
+            size_width_m: 1.0,
+            size_length_m: 1.0,
+            confidence: 0.9,
+            mission_id: "m1".into(),
+            observed_at: Utc::now(),
+        }
+    }
+
+    #[test]
+    fn group_key_returns_class_when_unknown() {
+        // Arrange
+        let s = Store::new(MapObjectsStoreConfig::default());
+        // Act + Assert
+        assert_eq!(s.group_key("tank"), "tank");
+    }
+
+    #[test]
+    fn group_key_collapses_similar_classes() {
+        // Arrange
+        let cfg = MapObjectsStoreConfig {
+            similar_classes: vec![vec!["tree".into(), "shrub".into()]],
+            ..MapObjectsStoreConfig::default()
+        };
+        let s = Store::new(cfg);
+        // Assert
+        assert_eq!(s.group_key("tree"), "tree");
+        assert_eq!(s.group_key("shrub"), "tree");
+        assert_eq!(s.group_key("rock"), "rock");
+    }
+
+    #[test]
+    fn empty_store_has_zero_len() {
+        // Arrange
+        let s = Store::new(MapObjectsStoreConfig::default());
+        // Assert
+        assert_eq!(s.len(), 0);
+    }
+
+    #[test]
+    fn first_classify_is_new() {
+        // Arrange
+        let mut s = Store::new(MapObjectsStoreConfig::default());
+        // Act
+        let c = s.classify(input(50.45, 30.52, "tank")).unwrap();
+        // Assert
+        assert!(matches!(c, Classification::New { .. }));
+        assert_eq!(s.len(), 1);
+    }
+}

crates/mapobjects_store/src/lib.rs

@@ -1,30 +1,30 @@
 //! `mapobjects_store` — H3-indexed on-device map of detected objects.
 //!
-//! Real implementation lands in:
-//! - AZ-665 `mapobjects_store_h3_classify`
-//! - AZ-666 `mapobjects_store_ignored_and_pass_sweep`
-//! - AZ-667 `mapobjects_store_hydrate_and_pending`
-//! - AZ-668 `mapobjects_store_persistence`
+//! AZ-665 ships the spatial index + classify path:
+//!   - `internal::h3_index` — `h3o` wrapper, cell lookup, k-ring queries,
+//!     haversine distance.
+//!   - `internal::store` — in-memory `(H3_cell, class_group) → MapObject`
+//!     hashmap with `classify(ClassifyInput) → Classification`.
+//!
+//! Remaining work tracked in:
+//!   - AZ-666 `mapobjects_store_ignored_and_pass_sweep`
+//!   - AZ-667 `mapobjects_store_hydrate_and_pending`
+//!   - AZ-668 `mapobjects_store_persistence`
+
+use std::sync::{Arc, Mutex};
 
 use serde::{Deserialize, Serialize};
 
 use shared::error::{AutopilotError, Result};
 use shared::health::ComponentHealth;
-use shared::models::detection::Detection;
 use shared::models::mapobject::MapObjectsBundle;
 use shared::models::poi::Poi;
 
-const NAME: &str = "mapobjects_store";
+mod internal;
 
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
-pub enum Classification {
-    New,
-    Moved,
-    Existing,
-    RemovedCandidate,
-    Ignored,
-}
+pub use internal::store::{Classification, ClassifyInput, MapObjectsStoreConfig};
+
+const NAME: &str = "mapobjects_store";
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case")]
@@ -39,32 +39,64 @@ pub enum SyncState {
     PushDeferred,
 }
 
-pub struct MapObjectsStore;
+/// Owns the in-memory map. Construct once at the composition root and
+/// share via the cloneable `MapObjectsStoreHandle`.
+pub struct MapObjectsStore {
+    inner: Arc<Mutex<internal::store::Store>>,
+}
 
 impl MapObjectsStore {
-    pub fn new() -> Self {
-        Self
+    pub fn new(config: MapObjectsStoreConfig) -> Self {
+        Self {
+            inner: Arc::new(Mutex::new(internal::store::Store::new(config))),
+        }
     }
 
     pub fn handle(&self) -> MapObjectsStoreHandle {
-        MapObjectsStoreHandle
+        MapObjectsStoreHandle {
+            inner: self.inner.clone(),
+        }
     }
 }
 
 impl Default for MapObjectsStore {
     fn default() -> Self {
-        Self::new()
+        Self::new(MapObjectsStoreConfig::default())
     }
 }
 
-#[derive(Clone, Copy)]
-pub struct MapObjectsStoreHandle;
+#[derive(Clone)]
+pub struct MapObjectsStoreHandle {
+    inner: Arc<Mutex<internal::store::Store>>,
+}
 
 impl MapObjectsStoreHandle {
-    pub async fn classify(&self, _detection: Detection) -> Result<Classification> {
-        Err(AutopilotError::NotImplemented(
-            "mapobjects_store::classify (AZ-665)",
-        ))
+    /// Classify a georeferenced detection. See `system-flows.md §F7`.
+    ///
+    /// Sync because the operation is in-memory and the p99 ≤ 1 ms budget
+    /// (per `description.md §9`) is easier to honour without crossing an
+    /// async boundary.
+    pub fn classify(&self, input: ClassifyInput) -> Result<Classification> {
+        let mut guard = self
+            .inner
+            .lock()
+            .map_err(|_| AutopilotError::Internal("mapobjects_store mutex poisoned".into()))?;
+        guard.classify(input)
+    }
+
+    /// Total number of MapObjects currently indexed. Useful for tests and
+    /// health surfaces.
+    pub fn len(&self) -> Result<usize> {
+        let guard = self
+            .inner
+            .lock()
+            .map_err(|_| AutopilotError::Internal("mapobjects_store mutex poisoned".into()))?;
+        Ok(guard.len())
+    }
+
+    /// `true` when the store has no indexed objects. Mirrors `len() == 0`.
+    pub fn is_empty(&self) -> Result<bool> {
+        Ok(self.len()? == 0)
     }
 
     pub async fn apply_decline(&self, _poi: Poi) -> Result<()> {
@@ -92,17 +124,81 @@ impl MapObjectsStoreHandle {
     }
 
     pub fn health(&self) -> ComponentHealth {
-        ComponentHealth::disabled(NAME)
+        match self.inner.lock() {
+            Ok(guard) => {
+                ComponentHealth::green(NAME).with_detail(format!("indexed_objects={}", guard.len()))
+            }
+            Err(_) => ComponentHealth::red(NAME, "mutex poisoned"),
+        }
+    }
+}
+
+trait HealthDetail {
+    fn with_detail(self, detail: impl Into<String>) -> Self;
+}
+
+impl HealthDetail for ComponentHealth {
+    fn with_detail(mut self, detail: impl Into<String>) -> Self {
+        self.detail = Some(detail.into());
+        self
     }
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
+    use chrono::Utc;
+
+    fn input(lat: f64, lon: f64, class: &str) -> ClassifyInput {
+        ClassifyInput {
+            gps_lat: lat,
+            gps_lon: lon,
+            mgrs: format!("MGRS({lat},{lon})"),
+            class: class.into(),
+            size_width_m: 1.0,
+            size_length_m: 1.0,
+            confidence: 0.9,
+            mission_id: "m1".into(),
+            observed_at: Utc::now(),
+        }
+    }
 
     #[test]
-    fn it_compiles() {
-        let h = MapObjectsStore::new().handle();
-        assert_eq!(h.health().level, shared::health::HealthLevel::Disabled);
+    fn handle_classify_new_then_existing() {
+        // Arrange
+        let store = MapObjectsStore::default();
+        let h = store.handle();
+
+        // Act
+        let first = h.classify(input(50.45, 30.52, "tank")).unwrap();
+        let second = h.classify(input(50.45, 30.52, "tank")).unwrap();
+
+        // Assert
+        let new_id = match first {
+            Classification::New { id } => id,
+            other => panic!("expected New, got {other:?}"),
+        };
+        match second {
+            Classification::Existing { id } => assert_eq!(id, new_id),
+            other => panic!("expected Existing, got {other:?}"),
+        }
+        assert_eq!(h.len().unwrap(), 1);
+    }
+
+    #[test]
+    fn health_reports_indexed_count() {
+        // Arrange
+        let store = MapObjectsStore::default();
+        let h = store.handle();
+        h.classify(input(50.45, 30.52, "tank")).unwrap();
+        // Act
+        let health = h.health();
+        // Assert
+        assert_eq!(health.level, shared::health::HealthLevel::Green);
+        assert!(health
+            .detail
+            .as_deref()
+            .unwrap()
+            .contains("indexed_objects=1"));
     }
 }