iris-vector-graph 1.99.1__tar.gz → 1.99.3__tar.gz

{iris_vector_graph-1.99.1 → iris_vector_graph-1.99.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iris-vector-graph
-Version: 1.99.1
+Version: 1.99.3
 Summary: Transactional Graph + Vector retrieval system for InterSystems IRIS with hybrid search, openCypher, and GraphQL APIs
 Project-URL: Homepage, https://github.com/intersystems-community/iris-vector-graph
 Project-URL: Documentation, https://github.com/intersystems-community/iris-vector-graph/tree/main/docs
@@ -816,13 +816,7 @@ conditions = tool("patient-123")  # → {"conditions": [...], "error": None}
 
  ## Changelog
 
-### v1.99.1 (2026-05-29)
-- **perf(spec-164)**: Seed-local k-hop fast path — `engine.khop_seedlocal(seed, hops, predicate, max_results)` and routed `engine.khop()` for `hops ≤ IVG_KHOP_SEEDLOCAL_MAX_HOPS` (default 2). Walks `^NKG(-1, sIdx, *, *)` directly via ObjectScript `$Order`, bypassing the Rust `KHopNeighbors` whole-graph serialization tax. **1-hop: 179µs → ≤150µs** (1.95× faster) on 50K-node / 145K-edge fixture. 2-hop: ≤300µs. Falls back to `^KG` walk when `^NKG` not built; emits `RuntimeWarning` once per Python process.
-- **fix(spec-164)**: `Graph.KG.GraphIndex.EmptyHLL` — fixed `..EmptyHLL()` → `##class(Graph.KG.GraphIndex).EmptyHLL()` to prevent `<No such method>` compile error when `Graph.KG.Edge.cls` is compiled in a fresh container.
-- **feat(spec-164)**: `IVG_TEST_PORT` env var for `scripts/test-container.sh up` — allows running `ivg-iris` on any free host port when default 1972 is occupied by other containers.
-- **soft-deprecation(spec-164)**: `Graph.KG.Traversal.KHopNeighborIds` and `KHop2NeighborIds` — docstring deprecation notice pointing at `KHopNeighborsSeedLocal` as the preferred path. Methods retained for backward compat.
-
-
+### v1.99.0 (2026-05-28)
 - **feat**: Spec 163 — Community Detection & Cluster Analysis Suite. Four new graph algorithms via the GraphStore protocol + Cypher procedures + dual-path architecture (arno Rust accelerator primary + LazyKG pure-Python fallback):
   - `engine.leiden_communities(max_levels, gamma, tol, top_k, mem_budget_mb, random_seed, progress_callback)` — Leiden community detection (Traag et al. 2019). At `gamma=1.0` uses `ModularityVertexPartition` (canonical Leiden); at `gamma != 1.0` uses `CPMVertexPartition` for resolution control. ARI = 1.0 with `leidenalg` reference (4-way benchmark on karate, ER(500), ER(2000)).
   - `engine.triangle_count(top_k, progress_callback)` — symmetrized triangle count + LCC. Pearson > 0.95 with `networkx.triangles(networkx.Graph(G_directed))` on Erdős-Rényi 100-node fixture.

{iris_vector_graph-1.99.1 → iris_vector_graph-1.99.3}/README.md

@@ -733,13 +733,7 @@ conditions = tool("patient-123")  # → {"conditions": [...], "error": None}
 
  ## Changelog
 
-### v1.99.1 (2026-05-29)
-- **perf(spec-164)**: Seed-local k-hop fast path — `engine.khop_seedlocal(seed, hops, predicate, max_results)` and routed `engine.khop()` for `hops ≤ IVG_KHOP_SEEDLOCAL_MAX_HOPS` (default 2). Walks `^NKG(-1, sIdx, *, *)` directly via ObjectScript `$Order`, bypassing the Rust `KHopNeighbors` whole-graph serialization tax. **1-hop: 179µs → ≤150µs** (1.95× faster) on 50K-node / 145K-edge fixture. 2-hop: ≤300µs. Falls back to `^KG` walk when `^NKG` not built; emits `RuntimeWarning` once per Python process.
-- **fix(spec-164)**: `Graph.KG.GraphIndex.EmptyHLL` — fixed `..EmptyHLL()` → `##class(Graph.KG.GraphIndex).EmptyHLL()` to prevent `<No such method>` compile error when `Graph.KG.Edge.cls` is compiled in a fresh container.
-- **feat(spec-164)**: `IVG_TEST_PORT` env var for `scripts/test-container.sh up` — allows running `ivg-iris` on any free host port when default 1972 is occupied by other containers.
-- **soft-deprecation(spec-164)**: `Graph.KG.Traversal.KHopNeighborIds` and `KHop2NeighborIds` — docstring deprecation notice pointing at `KHopNeighborsSeedLocal` as the preferred path. Methods retained for backward compat.
-
-
+### v1.99.0 (2026-05-28)
 - **feat**: Spec 163 — Community Detection & Cluster Analysis Suite. Four new graph algorithms via the GraphStore protocol + Cypher procedures + dual-path architecture (arno Rust accelerator primary + LazyKG pure-Python fallback):
   - `engine.leiden_communities(max_levels, gamma, tol, top_k, mem_budget_mb, random_seed, progress_callback)` — Leiden community detection (Traag et al. 2019). At `gamma=1.0` uses `ModularityVertexPartition` (canonical Leiden); at `gamma != 1.0` uses `CPMVertexPartition` for resolution control. ARI = 1.0 with `leidenalg` reference (4-way benchmark on karate, ER(500), ER(2000)).
   - `engine.triangle_count(top_k, progress_callback)` — symmetrized triangle count + LCC. Pearson > 0.95 with `networkx.triangles(networkx.Graph(G_directed))` on Erdős-Rényi 100-node fixture.

{iris_vector_graph-1.99.1 → iris_vector_graph-1.99.3}/iris_src/src/Graph/KG/GraphIndex.cls

@@ -91,7 +91,7 @@ ClassMethod UpdateStructuralHLL(sIdx As %Integer, pIdx As %Integer, oIdx As %Int
 	} Else {
 		While (b1 # 2) = 0 { Set lz = lz + 1, b1 = b1 \ 2 }
 	}
-	Set hll = $Get(^NKG("$agg", sIdx, pIdx, "hll"), ##class(Graph.KG.GraphIndex).EmptyHLL())
+	Set hll = $Get(^NKG("$agg", sIdx, pIdx, "hll"), ..EmptyHLL())
 	If lz > $List(hll, regIdx) {
 		Set $List(hll, regIdx) = lz
 		Set ^NKG("$agg", sIdx, pIdx, "hll") = hll

{iris_vector_graph-1.99.1 → iris_vector_graph-1.99.3}/iris_src/src/Graph/KG/NKGAccel.cls

@@ -1071,225 +1071,4 @@ ClassMethod Build2HopExact() As %Boolean
     Return 1
 }
 
-/// Spec 164 (FR-164-001..005): Seed-local k-hop walk via ^NKG without serializing
-/// the whole graph. ~5x faster than KHopNeighbors for hops=1.
-///
-/// Walks ^NKG(-1, sIdx, *, *) directly via $Order. Returns JSON array
-/// [{"node_id": ..., "hops": N}] ordered hops-ascending, then ^NKG subscript
-/// order within each hop (FR-164-001 / round-1 Q1 BFS layer order).
-///
-/// Edge cases (FR-164-004 / round-1 Q5):
-///   - hops=0          → "[]"
-///   - seedId not in $NI → delegate to KHopFromKGGlobalFallback
-///   - predicate not in $LI → "[]"
-///   - maxResults=0    → unlimited
-ClassMethod KHopNeighborsSeedLocal(seedId As %String, hops As %Integer = 1, predicate As %String = "", maxResults As %Integer = 10000) As %String
-{
-    If (seedId = "") || (hops = 0) {
-        Return "SEEDLOCAL:[]"
-    }
-    Set sIdx = $Get(^NKG("$NI", seedId))
-    If sIdx = "" {
-        Return "KGFALLBACK:"_..KHopFromKGGlobalFallback(seedId, hops, predicate, maxResults)
-    }
-
-    Kill ^||khopSeen, ^||khopResult
-    Set ^||khopSeen(sIdx) = 0
-    Set count = 0, frontStart = 1, frontEnd = 0
-    Set capped = 0
-    If predicate '= "" {
-        Set pIdx = $Get(^NKG("$LI", predicate))
-        If pIdx = "" {
-            Kill ^||khopSeen, ^||khopResult
-            Return "[]"
-        }
-        Set negP = -(pIdx + 1)
-        Set oIdx = $Order(^NKG(-1, sIdx, negP, ""))
-        While (oIdx '= "") && ('capped) {
-            If '$Data(^||khopSeen(oIdx)) {
-                Set ^||khopSeen(oIdx) = 1
-                Set count = count + 1
-                Set frontEnd = count
-                Set ^||khopResult(count, "id") = $Get(^NKG("$ND", oIdx))
-                Set ^||khopResult(count, "hops") = 1
-                Set ^||khopResult(count, "idx") = oIdx
-                If (maxResults > 0) && (count >= maxResults) Set capped = 1
-            }
-            Set oIdx = $Order(^NKG(-1, sIdx, negP, oIdx))
-        }
-    } Else {
-        Set negP = $Order(^NKG(-1, sIdx, ""))
-        While (negP '= "") && ('capped) {
-            Set oIdx = $Order(^NKG(-1, sIdx, negP, ""))
-            While (oIdx '= "") && ('capped) {
-                If '$Data(^||khopSeen(oIdx)) {
-                    Set ^||khopSeen(oIdx) = 1
-                    Set count = count + 1
-                    Set frontEnd = count
-                    Set ^||khopResult(count, "id") = $Get(^NKG("$ND", oIdx))
-                    Set ^||khopResult(count, "hops") = 1
-                    Set ^||khopResult(count, "idx") = oIdx
-                    If (maxResults > 0) && (count >= maxResults) Set capped = 1
-                }
-                Set oIdx = $Order(^NKG(-1, sIdx, negP, oIdx))
-            }
-            Set negP = $Order(^NKG(-1, sIdx, negP))
-        }
-    }
-
-    If (hops >= 2) && ('capped) {
-        For i = frontStart:1:frontEnd {
-            Quit:capped
-            Set fIdx = $Get(^||khopResult(i, "idx"))
-            If fIdx = "" Continue
-            If predicate '= "" {
-                Set pIdx2 = $Get(^NKG("$LI", predicate))
-                Quit:pIdx2=""
-                Set negP2 = -(pIdx2 + 1)
-                Set oIdx2 = $Order(^NKG(-1, fIdx, negP2, ""))
-                While (oIdx2 '= "") && ('capped) {
-                    If '$Data(^||khopSeen(oIdx2)) {
-                        Set ^||khopSeen(oIdx2) = 1
-                        Set count = count + 1
-                        Set ^||khopResult(count, "id") = $Get(^NKG("$ND", oIdx2))
-                        Set ^||khopResult(count, "hops") = 2
-                        Set ^||khopResult(count, "idx") = oIdx2
-                        If (maxResults > 0) && (count >= maxResults) Set capped = 1
-                    }
-                    Set oIdx2 = $Order(^NKG(-1, fIdx, negP2, oIdx2))
-                }
-            } Else {
-                Set negP2 = $Order(^NKG(-1, fIdx, ""))
-                While (negP2 '= "") && ('capped) {
-                    Set oIdx2 = $Order(^NKG(-1, fIdx, negP2, ""))
-                    While (oIdx2 '= "") && ('capped) {
-                        If '$Data(^||khopSeen(oIdx2)) {
-                            Set ^||khopSeen(oIdx2) = 1
-                            Set count = count + 1
-                            Set ^||khopResult(count, "id") = $Get(^NKG("$ND", oIdx2))
-                            Set ^||khopResult(count, "hops") = 2
-                            Set ^||khopResult(count, "idx") = oIdx2
-                            If (maxResults > 0) && (count >= maxResults) Set capped = 1
-                        }
-                        Set oIdx2 = $Order(^NKG(-1, fIdx, negP2, oIdx2))
-                    }
-                    Set negP2 = $Order(^NKG(-1, fIdx, negP2))
-                }
-            }
-        }
-    }
-
-    Set json = "["
-    Set sep = ""
-    For j = 1:1:count {
-        Set nid = $Get(^||khopResult(j, "id"))
-        Set h = $Get(^||khopResult(j, "hops"))
-        Set escNid = $Replace($Replace(nid, "\", "\\"), """", "\""")
-        Set json = json _ sep _ "{""node_id"":""" _ escNid _ """,""hops"":" _ h _ "}"
-        Set sep = ","
-    }
-    Set json = json _ "]"
-
-    Kill ^||khopSeen, ^||khopResult
-    Return "SEEDLOCAL:"_json
-}
-/// Spec 164 FR-164-008 / round-2 Q3 — `^KG` walk fallback when `^NKG("$NI", seedId)`
-/// is empty. Emits **identical JSON schema** to KHopNeighborsSeedLocal:
-///   [{"node_id": "...", "hops": N}, ...] hops-ascending, BFS layer order.
-/// Uses `^||khopSeenId` (string-keyed) for dedup since `^KG` is string-keyed.
-ClassMethod KHopFromKGGlobalFallback(seedId As %String, hops As %Integer = 1, predicate As %String = "", maxResults As %Integer = 10000) As %String [ Private ]
-{
-    If (seedId = "") || (hops = 0) {
-        Return "[]"
-    }
-
-    Kill ^||khopSeenId, ^||khopResult
-    Set ^||khopSeenId(seedId) = 0
-    Set count = 0, frontStart = 1, frontEnd = 0
-    Set capped = 0
-
-    If predicate '= "" {
-        Set dst = $Order(^KG("out", 0, seedId, predicate, ""))
-        While (dst '= "") && ('capped) {
-            If '$Data(^||khopSeenId(dst)) {
-                Set ^||khopSeenId(dst) = 1
-                Set count = count + 1
-                Set frontEnd = count
-                Set ^||khopResult(count, "id") = dst
-                Set ^||khopResult(count, "hops") = 1
-                If (maxResults > 0) && (count >= maxResults) Set capped = 1
-            }
-            Set dst = $Order(^KG("out", 0, seedId, predicate, dst))
-        }
-    } Else {
-        Set pred = $Order(^KG("out", 0, seedId, ""))
-        While (pred '= "") && ('capped) {
-            Set dst = $Order(^KG("out", 0, seedId, pred, ""))
-            While (dst '= "") && ('capped) {
-                If '$Data(^||khopSeenId(dst)) {
-                    Set ^||khopSeenId(dst) = 1
-                    Set count = count + 1
-                    Set frontEnd = count
-                    Set ^||khopResult(count, "id") = dst
-                    Set ^||khopResult(count, "hops") = 1
-                    If (maxResults > 0) && (count >= maxResults) Set capped = 1
-                }
-                Set dst = $Order(^KG("out", 0, seedId, pred, dst))
-            }
-            Set pred = $Order(^KG("out", 0, seedId, pred))
-        }
-    }
-
-    If (hops >= 2) && ('capped) {
-        For i = frontStart:1:frontEnd {
-            Quit:capped
-            Set fId = $Get(^||khopResult(i, "id"))
-            If fId = "" Continue
-            If predicate '= "" {
-                Set d2 = $Order(^KG("out", 0, fId, predicate, ""))
-                While (d2 '= "") && ('capped) {
-                    If '$Data(^||khopSeenId(d2)) {
-                        Set ^||khopSeenId(d2) = 1
-                        Set count = count + 1
-                        Set ^||khopResult(count, "id") = d2
-                        Set ^||khopResult(count, "hops") = 2
-                        If (maxResults > 0) && (count >= maxResults) Set capped = 1
-                    }
-                    Set d2 = $Order(^KG("out", 0, fId, predicate, d2))
-                }
-            } Else {
-                Set p2 = $Order(^KG("out", 0, fId, ""))
-                While (p2 '= "") && ('capped) {
-                    Set d2 = $Order(^KG("out", 0, fId, p2, ""))
-                    While (d2 '= "") && ('capped) {
-                        If '$Data(^||khopSeenId(d2)) {
-                            Set ^||khopSeenId(d2) = 1
-                            Set count = count + 1
-                            Set ^||khopResult(count, "id") = d2
-                            Set ^||khopResult(count, "hops") = 2
-                            If (maxResults > 0) && (count >= maxResults) Set capped = 1
-                        }
-                        Set d2 = $Order(^KG("out", 0, fId, p2, d2))
-                    }
-                    Set p2 = $Order(^KG("out", 0, fId, p2))
-                }
-            }
-        }
-    }
-
-    Set json = "["
-    Set sep = ""
-    For j = 1:1:count {
-        Set nid = $Get(^||khopResult(j, "id"))
-        Set h = $Get(^||khopResult(j, "hops"))
-        Set escNid = $Replace($Replace(nid, "\", "\\"), """", "\""")
-        Set json = json _ sep _ "{""node_id"":""" _ escNid _ """,""hops"":" _ h _ "}"
-        Set sep = ","
-    }
-    Set json = json _ "]"
-
-    Kill ^||khopSeenId, ^||khopResult
-    Return json
-}
-
 }

{iris_vector_graph-1.99.1 → iris_vector_graph-1.99.3}/iris_src/src/Graph/KG/Traversal.cls

@@ -1027,13 +1027,6 @@ ClassMethod KHopCount(srcId As %String, pred As %String = "") As %Integer
 
 /// Returns 1-hop neighbor IDs as a newline-delimited string — no JSON overhead.
 /// ~10x faster than BFSFastJson for large neighbor sets when only IDs are needed.
-/// DEPRECATED (spec 164, 2026-05-29): Prefer
-/// Graph.KG.NKGAccel.KHopNeighborsSeedLocal which walks ^NKG directly
-/// via $Order without the whole-graph serialization tax (~86µs vs ~455µs
-/// SQL BFS on 50K-node graph). This method is retained for backward
-/// compatibility with direct-classMethodValue callers outside the engine
-/// layer (custom dashboards, debug scripts); the engine itself now
-/// dispatches to KHopNeighborsSeedLocal for hops<=IVG_KHOP_SEEDLOCAL_MAX_HOPS.
 ClassMethod KHopNeighborIds(srcId As %String, pred As %String = "") As %String
 {
     Set result = ""
@@ -1132,9 +1125,6 @@ ClassMethod KHop2Count(srcId As %String, pred As %String = "") As %Integer
 
 /// Returns 2-hop distinct neighbor IDs as newline-delimited string.
 /// Excludes srcId. Uses process-private globals for dedup — no JSON.
-/// DEPRECATED (spec 164, 2026-05-29): Prefer
-/// Graph.KG.NKGAccel.KHopNeighborsSeedLocal(seedId, 2, ...) which walks ^NKG
-/// directly. See KHopNeighborIds deprecation notice for full rationale.
 ClassMethod KHop2NeighborIds(srcId As %String, pred As %String = "", maxResults As %Integer = 0) As %String
 {
     Kill ^||kh2s, ^||kh2all

{iris_vector_graph-1.99.1 → iris_vector_graph-1.99.3}/iris_vector_graph/cypher/translator.py

@@ -44,8 +44,6 @@ COMMUNITY_ALLOWED_KEYS: Dict[str, set] = {
     "ivg.kcore":          {"topK"},
 }
 
-KHOP_SEEDLOCAL_ALLOWED_KEYS: set = {"seed", "hops", "predicate", "maxResults"}
-
 
 def _validate_centrality_proc_map(proc_name: str, map_keys) -> None:
     """Reject unknown map-parameter keys for centrality procedures.
@@ -345,11 +343,9 @@ def translate_procedure_call(
         _translate_scc(proc, context)
     elif name == "ivg.kcore":
         _translate_kcore(proc, context)
-    elif name == "ivg.khopSeedLocal":
-        _translate_khop_seedlocal(proc, context)
     else:
         raise ValueError(
-            f"Unknown procedure: {name!r}. Supported: ivg.retrieve, ivg.vector.search, ivg.neighbors, ivg.ppr, ivg.bm25.search, ivg.ivf.search, ivg.shortestPath.weighted, ivg.degreeCentrality, ivg.betweenness, ivg.closeness, ivg.eigenvector, ivg.leiden, ivg.triangleCount, ivg.scc, ivg.kcore, ivg.khopSeedLocal"
+            f"Unknown procedure: {name!r}. Supported: ivg.retrieve, ivg.vector.search, ivg.neighbors, ivg.ppr, ivg.bm25.search, ivg.ivf.search, ivg.shortestPath.weighted, ivg.degreeCentrality, ivg.betweenness, ivg.closeness, ivg.eigenvector, ivg.leiden, ivg.triangleCount, ivg.scc, ivg.kcore"
         )
 
 
@@ -3903,53 +3899,3 @@ def _translate_kcore(proc, context) -> None:
         context.variable_aliases[item] = "KCore"
     if "coreness" in proc.yield_items:
         context.scalar_variables.add("coreness")
-
-
-def _validate_khop_seedlocal_proc_map(proc_name: str, map_keys) -> None:
-    """Reject unknown map-parameter keys for ivg.khopSeedLocal (Spec 164 FR-164-010 / round-2 Q4 / FR-015 precedent)."""
-    unknown = set(map_keys) - KHOP_SEEDLOCAL_ALLOWED_KEYS
-    if unknown:
-        raise ValueError(
-            f"Unknown parameters for {proc_name}: {sorted(unknown)}. "
-            f"Allowed: {sorted(KHOP_SEEDLOCAL_ALLOWED_KEYS)}"
-        )
-
-
-def _translate_khop_seedlocal(proc, context) -> None:
-    """Spec 164 FR-164-010 — Cypher → SQL CTE for CALL ivg.khopSeedLocal({...}).
-
-    Xfail-marked at e2e layer pending Bug S: the SQL function kg_KHopSeedLocal
-    calls ##class(Graph.KG.NKGAccel) which fails <CLASS DOES NOT EXIST> from
-    external SQL bindings. Python API path works. See ENGINEERING_DEBT.md Bug S.
-    """
-    opts = proc.options or {}
-    _validate_khop_seedlocal_proc_map("ivg.khopSeedLocal", opts.keys())
-
-    def _val(key, default):
-        v = opts.get(key, default)
-        if hasattr(v, "value"):
-            return v.value
-        return v
-
-    seed       = _val("seed", None)
-    hops       = int(_val("hops", 1))
-    predicate  = str(_val("predicate", ""))
-    max_results = int(_val("maxResults", 10000))
-
-    fn = f"{_schema_prefix}.kg_KHopSeedLocal" if _schema_prefix else "kg_KHopSeedLocal"
-    cte_sql = (
-        f"SELECT j.node_id AS node, j.hops\n"
-        f"FROM JSON_TABLE(\n"
-        f"  {fn}(?, ?, ?, ?),\n"
-        f"  '$[*]' COLUMNS(\n"
-        f"    node_id VARCHAR(256) PATH '$.node_id',\n"
-        f"    hops INTEGER PATH '$.hops'\n"
-        f"  )\n"
-        f") j"
-    )
-    context.all_stage_params.extend([seed, hops, predicate, max_results])
-    context.stages.insert(0, f"KHopSeedLocal AS (\n{cte_sql}\n)")
-    for item in proc.yield_items:
-        context.variable_aliases[item] = "KHopSeedLocal"
-    if "hops" in proc.yield_items:
-        context.scalar_variables.add("hops")

{iris_vector_graph-1.99.1 → iris_vector_graph-1.99.3}/iris_vector_graph/engine.py

@@ -8,7 +8,6 @@ that can be used across any domain.
 """
 
 import json
-import os
 from pathlib import Path
 from typing import Callable, List, Tuple, Optional, Dict, Any
 import logging
@@ -134,6 +133,7 @@ class IRISGraphEngine:
         self._rel_mapping_cache: Optional[Dict[tuple, dict]] = None
         self._connection_params: Optional[Dict[str, Any]] = None
         self._nkg_dirty: bool = False
+        self._shared_lkg = None
         self._index_registry: Dict[str, str] = self._build_index_registry()
         if vector_dtype == "DOUBLE":
             self.vector_dtype = self._detect_stored_vector_dtype()
@@ -146,6 +146,16 @@ class IRISGraphEngine:
         logger.debug("IRISGraphEngine initialized (dim=%s dtype=%s)",
                      embedding_dimension or "auto", self.vector_dtype)
 
+    def _get_shared_lkg(self, include_sinks: bool = True):
+        """Return the shared LazyKG instance, creating it on first call (spec 166 FR-166-002)."""
+        if self._shared_lkg is None:
+            from iris_vector_graph.stores.lazy_kg import LazyKG
+            self._shared_lkg = LazyKG(self.conn, include_sinks=include_sinks)
+        return self._shared_lkg
+
+    def _invalidate_shared_lkg(self) -> None:
+        self._shared_lkg = None
+
     @classmethod
     def from_connect(
         cls,
@@ -3290,6 +3300,7 @@ class IRISGraphEngine:
             _call_classmethod(self.conn, "Graph.KG.Traversal", "BuildKG")
             self.capabilities.kg_built = True
             self._nkg_dirty = True
+            self._invalidate_shared_lkg()
             logger.info("^KG adjacency index rebuilt successfully")
             return True
         except Exception as e:
@@ -3412,6 +3423,7 @@ class IRISGraphEngine:
             n += 1
         self.conn.commit()
         self._nkg_dirty = True
+        self._invalidate_shared_lkg()
         return n
 
     def load_networkx(
@@ -5990,20 +6002,7 @@ class IRISGraphEngine:
             for i in range(1, n + 1)
         )
 
-    def khop(self, seed: str, hops: int = 2, max_nodes: int = 500, predicate: str = "") -> dict:
-        """K-hop traversal with auto-routing (spec 164).
-
-        For `hops <= IVG_KHOP_SEEDLOCAL_MAX_HOPS` (default 2), routes to the
-        seed-local fast path (`engine.khop_seedlocal`). For larger `hops`,
-        falls through to the existing Rust/ObjectScript paths.
-        """
-        max_seedlocal = int(os.environ.get("IVG_KHOP_SEEDLOCAL_MAX_HOPS", "2"))
-        if hops <= max_seedlocal:
-            try:
-                return self.khop_seedlocal(seed, hops, predicate, max_nodes)
-            except Exception as e:
-                logger.warning(f"khop seedlocal failed, falling back to legacy path: {e}")
-
+    def khop(self, seed: str, hops: int = 2, max_nodes: int = 500) -> dict:
         if self._detect_arno() and "khop" in self._arno_capabilities.get(
             "algorithms", []
         ):
@@ -6016,81 +6015,6 @@ class IRISGraphEngine:
             logger.warning(f"Arno khop error: {parsed['error']}")
         return self._khop_fallback(seed, hops, max_nodes)
 
-    def khop_seedlocal(self, seed: str, hops: int = 1, predicate: str = "",
-                        max_results: int = 10000) -> dict:
-        """Seed-local k-hop via `^NKG` integer index (spec 164, FR-164-001 / FR-164-007).
-
-        Walks `^NKG(-1, sIdx, *, *)` directly via $Order, bypassing the Rust
-        `KHopNeighbors` whole-graph serialization tax. Returns
-        `{"path": "seedlocal" | "kg_fallback", "rows": [{"node_id":..., "hops":...}, ...]}`
-        ordered hops-ascending then `^NKG` subscript order within each hop
-        (round-1 Q1 BFS layer order).
-
-        Path discrimination (FR-164-008 round-3): we probe `^NKG("$NI", seed)`
-        via Native API (~5µs) BEFORE invoking the ClassMethod; if empty,
-        path="kg_fallback". Otherwise path="seedlocal".
-
-        Multi-predicate dedup (round-1 Q4): `predicate=""` walks all predicates
-        with per-node dedup via process-private `^||khop_seen(oIdx)`; first
-        predicate-subscript order wins.
-
-        Edge cases (FR-164-004):
-        - hops=0 → empty rows
-        - missing seed → empty rows + path="kg_fallback"
-        - max_results=0 → unlimited
-
-        Performance (NFR-164-001 / NFR-164-002 hard gates):
-        - 1-hop median ≤ 150µs on ER(50K, ~145K edges)
-        - 2-hop median ≤ 300µs on same fixture
-        """
-        max_seedlocal = int(os.environ.get("IVG_KHOP_SEEDLOCAL_MAX_HOPS", "2"))
-        if hops < 0 or hops > max_seedlocal:
-            raise ValueError(
-                f"khop_seedlocal hops={hops} out of range [0, {max_seedlocal}]; "
-                f"override via IVG_KHOP_SEEDLOCAL_MAX_HOPS"
-            )
-
-        try:
-            iris_obj = self._iris_obj()
-        except Exception:
-            return {"path": "seedlocal", "rows": []}
-
-        try:
-            raw = str(iris_obj.classMethodValue(
-                "Graph.KG.NKGAccel", "KHopNeighborsSeedLocal",
-                seed, hops, predicate, max_results,
-            ))
-        except Exception as e:
-            logger.warning(f"KHopNeighborsSeedLocal raised: {e}")
-            return {"path": "seedlocal", "rows": []}
-
-        if raw.startswith("KGFALLBACK:"):
-            path = "kg_fallback"
-            json_part = raw[len("KGFALLBACK:"):]
-            from iris_vector_graph.stores import _khop_state
-            if not _khop_state._khop_nkg_warning_emitted:
-                import warnings as _warnings
-                _warnings.warn(
-                    f"^NKG missing for seed {seed!r}; using ^KG walk fallback. "
-                    f"Call engine.rebuild_nkg() to enable the fast path. "
-                    f"This warning is emitted once per Python process.",
-                    RuntimeWarning,
-                    stacklevel=2,
-                )
-                _khop_state._khop_nkg_warning_emitted = True
-        elif raw.startswith("SEEDLOCAL:"):
-            path = "seedlocal"
-            json_part = raw[len("SEEDLOCAL:"):]
-        else:
-            path = "seedlocal"
-            json_part = raw
-
-        try:
-            rows = json.loads(json_part) if json_part else []
-        except json.JSONDecodeError:
-            rows = []
-        return {"path": path, "rows": rows}
-
     def _khop_fallback(self, seed: str, hops: int, max_nodes: int) -> dict:
         if self.capabilities.objectscript_deployed:
             try:
@@ -7209,6 +7133,7 @@ class IRISGraphEngine:
             validated.direction,
             validated.predicate or "",
             validated.top_k,
+            lkg=self._get_shared_lkg(),
         )
         if result.error:
             return []
@@ -7262,6 +7187,7 @@ class IRISGraphEngine:
             validated.top_k,
             validated.mem_budget_mb,
             progress_callback,
+            lkg=self._get_shared_lkg(),
         )
         if result.error:
             return []
@@ -7316,6 +7242,7 @@ class IRISGraphEngine:
             validated.max_hops,
             validated.top_k,
             progress_callback,
+            lkg=self._get_shared_lkg(),
         )
         if result.error:
             return []
@@ -7360,6 +7287,7 @@ class IRISGraphEngine:
             validated.tol,
             validated.top_k,
             progress_callback,
+            lkg=self._get_shared_lkg(),
         )
         if result.error:
             return []
@@ -7432,6 +7360,7 @@ class IRISGraphEngine:
             validated.max_levels, validated.gamma, validated.tol,
             validated.top_k, validated.mem_budget_mb,
             validated.random_seed, progress_callback,
+            lkg=self._get_shared_lkg(),
         )
         if result.error:
             return []
@@ -7460,7 +7389,7 @@ class IRISGraphEngine:
                 f"{type(self._store).__name__ if getattr(self, '_store', None) else 'None'}"
             )
 
-        result = self._store.execute_triangle_count(validated.top_k, progress_callback)
+        result = self._store.execute_triangle_count(validated.top_k, progress_callback, lkg=self._get_shared_lkg())
         if result.error:
             return []
         return [{"id": row[0], "triangles": row[1], "lcc": row[2]} for row in result.rows]
@@ -7479,7 +7408,7 @@ class IRISGraphEngine:
                 f"{type(self._store).__name__ if getattr(self, '_store', None) else 'None'}"
             )
 
-        result = self._store.execute_scc(validated.top_k, progress_callback)
+        result = self._store.execute_scc(validated.top_k, progress_callback, lkg=self._get_shared_lkg())
         if result.error:
             return []
         return [{"id": row[0], "component": row[1], "size": row[2]} for row in result.rows]
@@ -7498,7 +7427,7 @@ class IRISGraphEngine:
                 f"{type(self._store).__name__ if getattr(self, '_store', None) else 'None'}"
             )
 
-        result = self._store.execute_k_core(validated.top_k, progress_callback)
+        result = self._store.execute_k_core(validated.top_k, progress_callback, lkg=self._get_shared_lkg())
         if result.error:
             return []
         return [{"id": row[0], "coreness": row[1]} for row in result.rows]