test(kpm): raise M9 coverage — exclude examples + edge tests (#177) (#218)

* refactor(kpm): factor VisualDatabase::query matching loop + add query_from_keyframe (#147)

Recover part of the C++ query onion. Step 1 (no public API change): extract
the per-keyframe matching loop into `match_against_database` and the
per-query reset into `reset_query_state`. Step 2: expose
`query_from_keyframe(Keyframe)` — runs only the matching loop against the
database (skips pyramid build + feature extraction), for deterministic
testing and callers that already hold a `Keyframe`. Mirrors C++
`query(const keyframe_t*)`.

`query(&Matrix<u8>)` is now a thin wrapper (build keyframe → match → stash),
behaviorally identical (existing query tests unchanged + green).

Skipped per YAGNI: `query_from_pyramid` — KPM uses GaussianScaleSpacePyramid
while AR2 uses BoxFilterPyramid8u, so there is no possible cross-pipeline
caller (documented in #147).

Test: query_from_keyframe self-matches an identical keyframe.

Closes #147.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test(kpm): raise M9 coverage — exclude examples + edge tests (#177)

- coverage: exclude `examples/**` from tarpaulin (the 30-line
  simple_nft_dual.rs diagnostic at 0% was the single biggest gap; examples
  are demos, not test code — the issue's preferred fix).
- clustering: add a degenerate-input test (BHC build over all-identical
  descriptors → zero-distance k-medoids split + query).
- visual_database: add a no-match test via query_from_keyframe (#147) —
  maximally-distant descriptors short-circuit try_match_one.

Codecov on this PR confirms the resulting M9 module coverage; any residual
per-file gaps (rust_backend DualFreakMatcher divergence, hough 1-liner) are
quick follow-ups.

Refs #177.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: kalwalt

.github/workflows/coverage.yml

@@ -33,6 +33,7 @@ jobs:
             --output-dir coverage \
             --timeout 300 \
             --exclude-files "**/tests/*" \
+            --exclude-files "**/examples/*" \
             --ignore-panics
 
       - name: Upload coverage reports to Codecov

crates/core/src/kpm/freak/clustering.rs

@@ -876,6 +876,22 @@ mod tests {
         assert!(bhc.query(&feat).is_err());
     }
 
+    #[test]
+    fn test_bhc_build_all_identical() {
+        // Degenerate input: many identical descriptors. k-medoids distances are
+        // all zero, so the split is degenerate — exercise that path (#177).
+        let feat = [42u8; 96];
+        let owned: Vec<[u8; 96]> = (0..20).map(|_| feat).collect();
+        let features: Vec<&[u8; 96]> = owned.iter().collect();
+        let mut bhc = BinaryHierarchicalClustering::new().unwrap();
+        bhc.build(&features).expect("build over identical features");
+        let res = bhc.query(&feat).expect("query");
+        assert!(
+            !res.is_empty(),
+            "query of an identical feature must return the leaf members"
+        );
+    }
+
     #[test]
     fn test_bhc_roundtrip() {
         let mut bhc = BinaryHierarchicalClustering::new().unwrap();

crates/core/src/kpm/freak/visual_database.rs

@@ -1129,6 +1129,38 @@ mod tests {
         );
     }
 
+    #[test]
+    fn test_query_from_keyframe_no_match() {
+        // Deterministic, no image: a db keyframe with all-0x00 descriptors vs a
+        // query keyframe with all-0xFF descriptors — maximally distant, so the
+        // ratio test rejects every candidate and try_match_one short-circuits
+        // (no-match path, #177).
+        let mk = |desc: u8, n: usize| -> Keyframe {
+            let mut kf = Keyframe::new(640, 480).unwrap();
+            for i in 0..n {
+                let p = FeaturePoint {
+                    x: i as f32,
+                    y: i as f32,
+                    angle: 0.0,
+                    scale: 1.0,
+                    maxima: true,
+                };
+                kf.store.add(p, &[desc; 96]).unwrap();
+            }
+            kf
+        };
+
+        let mut db = VisualDatabase::new().expect("new");
+        db.add_keyframe(mk(0x00, 12), 0).expect("add_keyframe");
+
+        let matched = db
+            .query_from_keyframe(mk(0xFF, 12))
+            .expect("query_from_keyframe");
+        assert!(!matched, "maximally-distant descriptors must not match");
+        assert_eq!(db.matched_db_id(), -1);
+        assert!(db.inliers().is_empty());
+    }
+
     #[test]
     fn test_facade_parity_accessors() {
         // Build a tiny keyframe directly (no image pipeline) so the getters are