hypertopos 0.3.2__tar.gz → 0.3.3__tar.gz

{hypertopos-0.3.2 → hypertopos-0.3.3}/CHANGELOG.md

@@ -7,6 +7,15 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.3.3] — 2026-04-13
+
+### Added
+
+- `dim_mask` parameter on `find_similar_entities` — compute distance only on named dimensions. Focuses similarity search on specific aspects of geometry (e.g., only the dimensions driving an anomaly).
+- `metric` parameter on `find_similar_entities` — `"L2"` (default Euclidean) or `"cosine"` (shape similarity ignoring magnitude). Cosine compares anomaly profile direction, not severity.
+- `metric` parameter on `find_anomalies` (π5) — `"L2"` (default, pre-computed) or `"Linf"` (max single-dimension |delta|, runtime scan). Linf catches single-dimension spikes that L2 dilutes.
+- `push-mirrors.sh --from-ref` mode for incremental mirror pushes between tagged releases, with pre/post author verification guard.
+
 ## [0.3.2] — 2026-04-13
 
 ### Added

{hypertopos-0.3.2 → hypertopos-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypertopos
-Version: 0.3.2
+Version: 0.3.3
 Summary: Understand the structure of your data — without training machine learning models
 Project-URL: Homepage, https://github.com/hypertopos/hypertopos-py
 Project-URL: Documentation, https://github.com/hypertopos/hypertopos-py/tree/main/docs

{hypertopos-0.3.2 → hypertopos-0.3.3}/README.md

@@ -8,7 +8,7 @@
 [![PyArrow](https://img.shields.io/badge/format-PyArrow-red.svg)](https://arrow.apache.org/docs/python/)
 [![Lance](https://img.shields.io/badge/storage-Lance-blueviolet.svg)](https://github.com/lance-format/lance)
 [![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io)
-[![Version](https://img.shields.io/badge/version-0.3.1-%235500FF.svg)](pyproject.toml)
+[![Version](https://img.shields.io/badge/version-0.3.3-%235500FF.svg)](pyproject.toml)
 
 hypertopos transforms relational data into a geometric space where every entity gets a coordinate derived from its relationships. Distance from the population center reveals anomalies. Proximity between entities reveals similarity. Movement over time reveals drift. No training, no labels — geometry is computed from the data.
 

hypertopos-0.3.3/ROADMAP.md

@@ -0,0 +1,84 @@
+# hypertopos — Roadmap
+
+> Planned direction. Priorities may change based on feedback.
+
+## Plan: 0.4.0
+
+Investigation depth + detection quality — new geometric primitives, agent trust, calibration.
+
+- **Lazy chain geometry** — on-demand chain delta vectors via sampled population calibration; `discover_chains(include_geometry=True)` supplements build-time `chain_lines` for per-entity investigation without rebuild cost.
+- **Multi-hop anomaly explanation chains** — automate the trace-to-root-cause workflow: anomalous entity → top dimension → edge entity → hub check → neighbor check → explanation chain with per-hop evidence. Collapses 4–6 tool calls into one.
+- **Theta calibration fix** — builder writes correct theta_norm to sphere.json at build time; eliminates miscalibration on mixed-type patterns.
+- **Geometric edge potential** — relationship anomaly scoring via endpoint geometric distance; flags edges connecting geometrically distant entities.
+- **Geometric dark matter** — population density gap detection; identifies coordinate-space regions that should have entities but are empty (anomaly by absence).
+- **Gradient alignment on drift** — drift direction signal (normalizing vs deteriorating) on `find_drifting_entities` and `dive_solid`.
+- **Interpretive MCP output** — computed interpretation fields on tool responses (`passive_scan`, `find_similar_entities`, `dive_solid`, `find_regime_changes`) so agents stop misreading raw numbers.
+- **Anomaly confidence via bootstrap** — `anomaly_confidence: 0–1` per entity quantifying how stable the anomaly verdict is under population perturbation.
+
+---
+
+## Plan: 0.5.0
+
+Edge-derived geometry + advanced analytics.
+
+- **Edge-derived dimensions on event patterns** — pair-level and node-derived features computed at build time as geometric dimensions.
+- **`find_motif` — structural pattern matching on edge table** — per-hop predicates for subgraph patterns invisible to flat queries.
+- **Advanced coordinate space analytics** — new methods leveraging properties unique to population-relative coordinate construction.
+
+---
+
+## 0.3.0
+
+Lance perf upgrade, FDR control, builder intelligence.
+
+- **0.3.0** — Aggregate engine rewritten around Lance SQL, precomputed contagion stats, format 2.2, edge table auto-detect fix.
+- **0.3.1** — Benjamini-Hochberg FDR control, submodular facility location, vectorized build with adaptive memory chunking.
+- **0.3.2** — NumPy graph features, chunked pre-computation, Lance compact tuning, per-dim index removal. Generalized dimension blocks (g/t/s), geometric heredity (`find_novel_entities`).
+- **0.3.3** — Agent navigation policy (investigation memory, failure guards, decision scoring). Dimension-selective similarity (`dim_mask`, `metric="cosine"`, `metric="Linf"`). Sphere-specific hardcoding removed from 6 skill guidance texts.
+
+---
+
+## 0.2.0
+
+Graph meets geometry — edge table, runtime traversal, contagion/influence.
+
+- **0.2.0** — Edge table, +11 navigator functions, contagion/influence primitives.
+- **0.2.1** — Witness cohort discovery, investigative peer ranking.
+- **0.2.2** — As-of graph reconstruction, `detect_cross_pattern_discrepancy` latency fix.
+
+---
+
+## 0.1.0
+
+First public release — full GDS stack, π1–π12, builder, MCP server, validation suite.
+
+---
+
+## Future
+
+**Detection quality**
+- Edge-derived dimensions + temporal motif matcher
+- Confidence scoring, robust estimators, multi-scale resolution — improve anomaly precision and reduce false positives on heavy-tail and multi-modal populations
+
+**Builder evolution**
+- Incremental rebuild — geometry-only without `--force` wipe
+
+**PassiveScanner evolution**
+- Native temporal source support for direct temporal inputs, without requiring manual dataset plumbing in benchmark scripts
+- Optional weighted scoring mode that uses continuous intensity instead of binary counts
+- **SphereProfiler** — autonomous sphere scanner that profiles all patterns, runs calibration sweeps across source combinations, proposes optimal PassiveScanner composition for Layer 1 surveillance.
+
+**Code refactoring**
+- Break up oversized modules into smaller, domain-focused components
+- Reduce coupling between core layers
+- Consolidate repeated orchestration logic into shared helpers
+
+**Cross-sphere capabilities**
+- Cross-sphere comparison — dimensionless metrics across independently calibrated coordinate spaces
+- What-if analysis — hypothetical edge changes producing modified coordinate vectors
+
+**Enterprise / governance**
+- Dimension access control — per-agent visibility constraints on delta dimensions
+
+**Tooling**
+- Runtime latency benchmarks in package docs

{hypertopos-0.3.2 → hypertopos-0.3.3}/SECURITY.md

@@ -1,6 +1,6 @@
 # Security
 
-## Current version: 0.3.2
+## Current version: 0.3.3
 
 hypertopos runs locally. No network services, no auth layer, no multi-tenancy.
 

{hypertopos-0.3.2 → hypertopos-0.3.3}/docs/api-reference.md

@@ -143,7 +143,7 @@ with sphere.session("agent-1") as session:
 |--------|-------------|
 | `explain_anomaly(primary_key, pattern_id)` | Structured investigation: severity, witness set, repair set, conformal p-value, reputation |
 | `explain_anomaly_chain(primary_key, pattern_id, max_hops)` | Trace anomaly propagation through geometric neighbors |
-| `find_similar_entities(primary_key, pattern_id, top_n)` | ANN search for nearest entities in delta-space. Returns `SimilarityResult` |
+| `find_similar_entities(primary_key, pattern_id, top_n, dim_mask, metric)` | ANN search for nearest entities in delta-space. `dim_mask`: list of dimension names to restrict distance. `metric`: `"L2"` or `"cosine"`. Returns `SimilarityResult` |
 | `contrast_populations(pattern_id, group_a, group_b)` | Dimension-by-dimension comparison of two entity groups (Cohen's d) |
 | `composite_risk(primary_key, line_id)` | Fisher's method combination of conformal p-values across patterns |
 | `composite_risk_batch(primary_keys, line_id)` | Batch Fisher combination for multiple entities |

{hypertopos-0.3.2 → hypertopos-0.3.3}/hypertopos/engine/geometry.py

@@ -553,44 +553,105 @@ class GDSEngine:
         top_n: int = 5,
         exclude_keys: set[str] | None = None,
         filter_expr: str | None = None,
+        dim_mask_indices: list[int] | None = None,
+        metric: str = "L2",
     ) -> list[tuple[str, float]]:
         """Find top-n nearest entities. Uses Lance ANN index when available.
 
-        filter_expr: optional Lance SQL predicate passed to ANN (e.g. 'is_anomaly = true').
-        On the NumPy fallback path the expression is ignored (caller responsibility).
+        filter_expr: optional Lance SQL predicate passed to ANN.
+        dim_mask_indices: compute distance only on these dimension indices.
+        metric: "L2" (Euclidean) or "cosine" (1 - cos_sim).
         """
-        # Fast path: Lance IVF_FLAT ANN
+        need_rerank = dim_mask_indices is not None or metric != "L2"
+
+        # Fast path: Lance IVF_FLAT ANN (L2 only, full vector)
         _ann_fn = getattr(self._storage, "find_nearest_lance", None)
-        if _ann_fn is not None:
+        if _ann_fn is not None and not need_rerank:
             ann = _ann_fn(pattern_id, version, ref_delta, top_n, exclude_keys, filter_expr)
             if ann is not None:
                 return ann
 
-        # Fallback: brute-force NumPy (non-indexed Lance)
+        # Over-fetch from ANN when we need to re-rank
+        if _ann_fn is not None and need_rerank:
+            ann = _ann_fn(
+                pattern_id, version, ref_delta, top_n * 5,
+                exclude_keys, filter_expr,
+            )
+            if ann is not None:
+                ann_keys = {k for k, _ in ann}
+                geo = self._storage.read_geometry(
+                    pattern_id, version,
+                    columns=["primary_key", "delta"],
+                    point_keys=list(ann_keys),
+                )
+                keys = geo["primary_key"].to_pylist()
+                deltas = delta_matrix_from_arrow(geo)
+                distances = self._compute_distances(
+                    ref_delta, deltas, dim_mask_indices, metric,
+                )
+                if exclude_keys:
+                    mask = np.array([k in exclude_keys for k in keys])
+                    distances[mask] = np.inf
+                return self._top_n_from_distances(keys, distances, top_n)
+
+        # Fallback: brute-force NumPy
         geo = self._storage.read_geometry(
             pattern_id, version, columns=["primary_key", "delta"],
         )
         keys = geo["primary_key"].to_pylist()
         deltas = delta_matrix_from_arrow(geo)
 
-        _diff = deltas - ref_delta.astype(np.float32)
-        distances = np.sqrt(np.einsum('ij,ij->i', _diff, _diff))
+        distances = self._compute_distances(
+            ref_delta, deltas, dim_mask_indices, metric,
+        )
 
         if exclude_keys:
             mask = np.array([k in exclude_keys for k in keys])
             distances[mask] = np.inf
 
+        return self._top_n_from_distances(keys, distances, top_n)
+
+    @staticmethod
+    def _compute_distances(
+        ref: np.ndarray,
+        candidates: np.ndarray,
+        dim_mask_indices: list[int] | None,
+        metric: str,
+    ) -> np.ndarray:
+        ref_f = ref.astype(np.float32)
+        cand = candidates
+
+        if dim_mask_indices is not None:
+            idx = np.array(dim_mask_indices, dtype=np.intp)
+            ref_f = ref_f[idx]
+            cand = cand[:, idx]
+
+        if metric == "cosine":
+            ref_norm = np.linalg.norm(ref_f)
+            cand_norms = np.linalg.norm(cand, axis=1)
+            safe_denom = np.maximum(ref_norm * cand_norms, 1e-10)
+            cos_sim = cand @ ref_f / safe_denom
+            return 1.0 - cos_sim
+
+        # L2 (default)
+        diff = cand - ref_f
+        return np.sqrt(np.einsum('ij,ij->i', diff, diff))
+
+    @staticmethod
+    def _top_n_from_distances(
+        keys: list[str],
+        distances: np.ndarray,
+        top_n: int,
+    ) -> list[tuple[str, float]]:
         finite_count = int(np.sum(np.isfinite(distances)))
         n = min(top_n, finite_count)
         if n == 0:
             return []
-
         if n >= len(distances):
             top_indices = np.argsort(distances)[:n]
         else:
             top_indices = np.argpartition(distances, n)[:n]
             top_indices = top_indices[np.argsort(distances[top_indices])]
-
         return [(keys[i], float(distances[i])) for i in top_indices]
 
     def find_clusters(

{hypertopos-0.3.2 → hypertopos-0.3.3}/hypertopos/navigation/navigator.py

@@ -735,6 +735,7 @@ class GDSNavigator:
         fdr_alpha: float | None = None,
         fdr_method: str = "bh",
         select: str = "top_norm",
+        metric: str = "L2",
     ) -> tuple[list[Polygon], int, list[dict] | None, dict | None]:
         """Find the most anomalous polygons in a pattern.
 
@@ -748,6 +749,8 @@ class GDSNavigator:
             raise NotImplementedError(
                 f"Only fdr_method='bh' is supported, got {fdr_method!r}"
             )
+        if metric not in ("L2", "Linf"):
+            raise ValueError(f"metric must be 'L2' or 'Linf', got '{metric}'")
         version = self._resolve_version(pattern_id)
         sphere = self._storage.read_sphere()
         pattern = sphere.patterns[pattern_id]
@@ -779,7 +782,7 @@ class GDSNavigator:
             )
         except _NAVIGATION_RECOVERABLE_ERRORS:
             _geo_count = 0
-        if _geo_count > 500_000 and rank_by_property is None:
+        if _geo_count > 500_000 and rank_by_property is None and metric == "L2":
             from hypertopos.engine.lance_sql_agg import (
                 find_anomalies as _lance_sql_find_anomalies,
             )
@@ -828,13 +831,19 @@ class GDSNavigator:
         # ------------------------------------------------------------------
 
         # Pass 1: light scan — push delta_norm >= threshold to Lance scanner
+        # Linf metric: can't use pre-computed delta_norm, read all geometry
         cols = list(self._LIGHT_COLUMNS)
         if missing_edge_to:
             cols.append("edges")
-        light = self._storage.read_geometry(
-            pattern_id, version, columns=cols,
-            filter=f"delta_norm >= {threshold}",
-        )
+        if metric == "Linf":
+            light = self._storage.read_geometry(
+                pattern_id, version, columns=cols,
+            )
+        else:
+            light = self._storage.read_geometry(
+                pattern_id, version, columns=cols,
+                filter=f"delta_norm >= {threshold}",
+            )
         if light.num_rows == 0:
             emerging = self._find_emerging(
                 pattern_id, version, pattern, include_emerging, offset, top_n,
@@ -854,7 +863,10 @@ class GDSNavigator:
 
         # Vectorized recompute + rank
         delta_matrix = delta_matrix_from_arrow(light)
-        norms = np.sqrt(np.einsum('ij,ij->i', delta_matrix, delta_matrix)).astype(np.float32)
+        if metric == "Linf":
+            norms = np.max(np.abs(delta_matrix), axis=1).astype(np.float32)
+        else:
+            norms = np.sqrt(np.einsum('ij,ij->i', delta_matrix, delta_matrix)).astype(np.float32)
         valid = norms >= threshold
         if not np.any(valid):
             emerging = self._find_emerging(
@@ -2119,6 +2131,8 @@ class GDSNavigator:
         top_n: int = 5,
         filter_expr: str | None = None,
         missing_edge_to: str | None = None,
+        dim_mask: list[str] | None = None,
+        metric: str = "L2",
     ) -> SimilarityResult:
         """Find top_n entities most similar to primary_key by delta vector distance.
 
@@ -2158,6 +2172,25 @@ class GDSNavigator:
             raise KeyError(f"Entity '{primary_key}' not found in {pattern_id} v{version}")
         ref_delta = np.array(table["delta"][0].as_py(), dtype=np.float32)
 
+        # Resolve dim_mask names → indices
+        dim_mask_indices: list[int] | None = None
+        if dim_mask is not None:
+            if not dim_mask:
+                raise ValueError("dim_mask must be non-empty")
+            pattern = sphere.patterns[pattern_id]
+            labels = pattern.dim_labels
+            dim_mask_indices = []
+            for name in dim_mask:
+                if name in labels:
+                    dim_mask_indices.append(labels.index(name))
+                else:
+                    raise ValueError(
+                        f"Unknown dimension '{name}' in dim_mask. "
+                        f"Available: {labels}"
+                    )
+        if metric not in ("L2", "cosine"):
+            raise ValueError(f"metric must be 'L2' or 'cosine', got '{metric}'")
+
         # Over-fetch when post-filter will remove some results
         fetch_n = top_n * 5 if missing_edge_to else top_n
 
@@ -2168,6 +2201,8 @@ class GDSNavigator:
             top_n=fetch_n,
             exclude_keys={primary_key},
             filter_expr=filter_expr,
+            dim_mask_indices=dim_mask_indices,
+            metric=metric,
         )
 
         if missing_edge_to and results:

{hypertopos-0.3.2 → hypertopos-0.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hypertopos"
-version = "0.3.2"
+version = "0.3.3"
 description = "Understand the structure of your data — without training machine learning models"
 requires-python = ">=3.12"
 license = {text = "BSL-1.1"}

{hypertopos-0.3.2 → hypertopos-0.3.3}/tests/test_navigation.py

@@ -1336,7 +1336,8 @@ def test_find_similar_entities():
             pass
 
         def find_nearest(
-            self, ref_delta, pattern_id, version, top_n=5, exclude_keys=None, filter_expr=None
+            self, ref_delta, pattern_id, version, top_n=5, exclude_keys=None,
+            filter_expr=None, dim_mask_indices=None, metric="L2",
         ):
             return [("CUST-002", 0.15), ("CUST-003", 0.42)]
 
@@ -1381,7 +1382,8 @@ def test_find_similar_entities_event_pattern():
             pass
 
         def find_nearest(
-            self, ref_delta, pattern_id, version, top_n=5, exclude_keys=None, filter_expr=None
+            self, ref_delta, pattern_id, version, top_n=5, exclude_keys=None,
+            filter_expr=None, dim_mask_indices=None, metric="L2",
         ):
             # Confirm event pattern_id is passed through unchanged
             assert pattern_id == "gl_pattern"
@@ -1427,7 +1429,8 @@ def test_find_similar_entities_passes_filter_expr():
             pass
 
         def find_nearest(
-            self, ref_delta, pattern_id, version, top_n=5, exclude_keys=None, filter_expr=None
+            self, ref_delta, pattern_id, version, top_n=5, exclude_keys=None,
+            filter_expr=None, dim_mask_indices=None, metric="L2",
         ):
             captured["filter_expr"] = filter_expr
             return [("CUST-002", 0.10)]
@@ -1457,6 +1460,182 @@ def test_find_similar_entities_passes_filter_expr():
     assert results[0][0] == "CUST-002"
 
 
+def test_find_similar_dim_mask():
+    """find_similar_entities with dim_mask computes distance only on selected dims."""
+    captured: dict = {}
+
+    class _MaskEngine:
+        def build_polygon(self, bk, pid, manifest):
+            poly = _make_polygon_with_edge("PROD-001", "products")
+            poly.delta = np.array([1.0, 0.0, 3.0], dtype=np.float32)
+            poly.delta_norm = float(np.linalg.norm(poly.delta))
+            return poly
+
+        def build_solid(self, *a, **kw):
+            pass
+
+        def find_nearest(
+            self, ref_delta, pattern_id, version, top_n=5,
+            exclude_keys=None, filter_expr=None,
+            dim_mask_indices=None, metric="L2",
+        ):
+            captured["dim_mask_indices"] = dim_mask_indices
+            captured["ref_delta"] = ref_delta.copy()
+            return [("CUST-002", 0.5)]
+
+    class _FakePattern:
+        pattern_type = "anchor"
+
+        @property
+        def dim_labels(self):
+            return ["_d_amount", "_d_count", "_d_score"]
+
+    class _FakeSphere:
+        lines = {}
+        patterns = {"customer_pattern": _FakePattern()}
+
+    class _MaskStorage(_MockStorageWithDelta):
+        def read_geometry(self, pattern_id, version, primary_key=None, columns=None, **kw):
+            import pyarrow as pa
+            if primary_key is None:
+                return pa.table({})
+            return pa.table({"delta": [[1.0, 0.0, 3.0]]})
+
+        def read_sphere(self):
+            return _FakeSphere()
+
+    manifest = Manifest(
+        manifest_id="test", agent_id="a",
+        snapshot_time=datetime(2024, 1, 1, tzinfo=UTC), status="active",
+        line_versions={"customers": 1}, pattern_versions={"customer_pattern": 1},
+    )
+    contract = Contract("test", ["customer_pattern"])
+    nav = GDSNavigator(
+        engine=_MaskEngine(), storage=_MaskStorage(),
+        manifest=manifest, contract=contract,
+    )
+
+    results = nav.find_similar_entities(
+        "CUST-001", "customer_pattern", top_n=1,
+        dim_mask=["_d_amount", "_d_score"],
+    )
+
+    assert captured["dim_mask_indices"] == [0, 2]
+    assert len(results) == 1
+
+
+def test_find_similar_cosine_metric():
+    """find_similar_entities with metric='cosine' passes metric to engine."""
+    captured: dict = {}
+
+    class _CosEngine:
+        def build_polygon(self, bk, pid, manifest):
+            poly = _make_polygon_with_edge("PROD-001", "products")
+            poly.delta = np.array([0.1, 0.2], dtype=np.float32)
+            poly.delta_norm = float(np.linalg.norm(poly.delta))
+            return poly
+
+        def build_solid(self, *a, **kw):
+            pass
+
+        def find_nearest(
+            self, ref_delta, pattern_id, version, top_n=5,
+            exclude_keys=None, filter_expr=None,
+            dim_mask_indices=None, metric="L2",
+        ):
+            captured["metric"] = metric
+            return [("CUST-002", 0.1)]
+
+    manifest = Manifest(
+        manifest_id="test", agent_id="a",
+        snapshot_time=datetime(2024, 1, 1, tzinfo=UTC), status="active",
+        line_versions={"customers": 1, "products": 1},
+        pattern_versions={"customer_pattern": 1},
+    )
+    contract = Contract("test", ["customer_pattern"])
+    nav = GDSNavigator(
+        engine=_CosEngine(), storage=_MockStorageWithDelta(),
+        manifest=manifest, contract=contract,
+    )
+
+    results = nav.find_similar_entities(
+        "CUST-001", "customer_pattern", top_n=1, metric="cosine",
+    )
+
+    assert captured["metric"] == "cosine"
+    assert len(results) == 1
+
+
+def test_find_nearest_cosine_distance():
+    """Engine.find_nearest with metric='cosine' returns cosine distances."""
+    from hypertopos.engine.geometry import GDSEngine
+
+    class _FakeStorage:
+        def find_nearest_lance(self, *a, **kw):
+            return None
+
+        def read_geometry(self, pattern_id, version, columns=None, **kw):
+            import pyarrow as pa
+            # Entity A: [1, 0], Entity B: [0, 1], Entity C: [1, 1]
+            return pa.table({
+                "primary_key": ["A", "B", "C"],
+                "delta": [[1.0, 0.0], [0.0, 1.0], [0.707, 0.707]],
+            })
+
+    engine = GDSEngine(storage=_FakeStorage(), cache=None)
+    # Reference: [1, 0] — C should be closer by cosine than B
+    ref = np.array([1.0, 0.0], dtype=np.float32)
+    results = engine.find_nearest(
+        ref, "p", 1, top_n=3, metric="cosine",
+    )
+
+    keys = [r[0] for r in results]
+    assert "A" in keys
+    # A = same direction → distance ~0
+    a_dist = next(d for k, d in results if k == "A")
+    c_dist = next(d for k, d in results if k == "C")
+    b_dist = next(d for k, d in results if k == "B")
+    assert a_dist < c_dist < b_dist
+
+
+def test_find_nearest_dim_mask():
+    """Engine.find_nearest with dim_mask_indices computes masked distance."""
+    from hypertopos.engine.geometry import GDSEngine
+
+    class _FakeStorage:
+        def find_nearest_lance(self, *a, **kw):
+            return None
+
+        def read_geometry(self, pattern_id, version, columns=None, **kw):
+            import pyarrow as pa
+            # Dim 0 differs, dim 1 identical
+            return pa.table({
+                "primary_key": ["A", "B"],
+                "delta": [[5.0, 1.0], [0.0, 1.0]],
+            })
+
+    engine = GDSEngine(storage=_FakeStorage(), cache=None)
+    ref = np.array([0.0, 1.0], dtype=np.float32)
+
+    # Without mask: A is far (dim 0 = 5.0 diff), B is close
+    results_full = engine.find_nearest(ref, "p", 1, top_n=2)
+    assert results_full[0][0] == "B"
+
+    # With mask on dim 1 only: both A and B have dim 1 = 1.0, distance = 0
+    results_masked = engine.find_nearest(
+        ref, "p", 1, top_n=2, dim_mask_indices=[1],
+    )
+    assert results_masked[0][1] == pytest.approx(0.0, abs=1e-5)
+    assert results_masked[1][1] == pytest.approx(0.0, abs=1e-5)
+
+
+def test_find_anomalies_linf_metric():
+    """find_anomalies with metric='Linf' ranks by max single-dimension delta."""
+    # This test verifies the navigator accepts the metric parameter.
+    # Full integration tested via MCP smoke.
+    pass  # placeholder — needs session-scoped fixture sphere
+
+
 def test_get_entity_geometry_meta_returns_stored_values():
     """get_entity_geometry_meta reads delta_norm, is_anomaly, delta_rank_pct from storage."""
     from unittest.mock import MagicMock