iris-vector-graph 1.88.0__tar.gz → 1.90.0__tar.gz

{iris_vector_graph-1.88.0 → iris_vector_graph-1.90.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iris-vector-graph
-Version: 1.88.0
+Version: 1.90.0
 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
@@ -753,6 +753,45 @@ anchors = engine.get_kg_anchors(icd_codes=["J18.0", "E11.9"])
 
  ## Changelog
 
+### v1.88.0 (2026-05-07)
+- **feat**: `ffi_kg_build_2hop_exact_int` Rust function — integer-indexed single-pass 2-hop dedup from `^KG("out")`. Writes results to `^ArnoKG("2h")` temp global; `DecodeBuildResults()` ObjectScript method converts to `^KG("deg2p_exact")`
+- **feat**: `KHop2CountExact(src, pred)` ObjectScript method — O(1) `$Get(^KG("deg2p_exact"))`, fallback to `KHop2Count` when not populated. 0.14ms p50 on SF10 (was 70ms)
+- **feat**: `Build2HopExactStats()` — Rust-first (tries `kg_build_2hop_exact_int`), ObjectScript fallback. Called automatically by `BuildNKG` and `engine.rebuild_nkg()`
+- **feat**: `engine.khop2_count_exact(node_id, pred)` — public method with `KHop2Input` validation
+- **feat**: `engine.backfill_deg2p_exact()` — populate `^KG("deg2p_exact")` for graphs loaded via `BulkIngestEdges`
+- **feat**: `execute_cypher` `[:P*2] RETURN count(n)` fast path now routes to `KHop2CountExact` (exact, not upper bound)
+- **test**: `tests/e2e/test_ic3_exact_count.py` — correctness + perf validation for 2-hop exact COUNT
+- **test**: `tests/e2e/test_untested_methods.py` — 113/113 public engine methods now have at least one test (100% coverage)
+
+### v1.87.0 (2026-05-07)
+- **feat**: `iris_vector_graph/_validate.py` — 10 Pydantic `BaseModel` input schemas for high-risk engine methods: `NodeIdInput`, `EdgeInput`, `CypherInput`, `IVFBuildInput`, `VectorSearchInput`, `BM25BuildInput`, `BM25SearchInput`, `KHop2Input`, `TemporalEdgeInput`, `VecSearchInput`
+- **feat**: Input validation at call entry on `execute_cypher`, `create_node`, `create_edge`, `ivf_build`, `ivf_search`, `bm25_build`, `bm25_search`, `khop2_count_fast`, `create_edge_temporal`, `search_nodes_by_vector`
+- All 10 schemas exported from `iris_vector_graph.__init__`; 44/44 unit tests in `test_validation.py`
+- **chore**: `BulkIngestEdges` marked `[ Internal ]` in `EdgeScan.cls` — safe path is `engine.bulk_ingest_edges()`
+
+### v1.86.0 (2026-05-07)
+- **feat**: `IVGResult` Pydantic `BaseModel` replaces `Dict[str, Any]` as return type of `execute_cypher`
+  - Backward-compatible: `result["columns"]`, `result.get("error")`, `"error" in result` all work
+  - `bool(result)` = `True` on success, `False` on error
+  - `result.columns`, `result.rows`, `result.error`, `result.metadata`, `result.sql` via dot notation
+  - 23 unit tests in `test_ivgresult.py`; all 189+ existing call sites pass unchanged
+- **feat**: Fourth Pydantic increment — `IVGResult` joins `SQLQuery`, `QueryMetadata`, `IndexHandle`
+
+### v1.85.0 (2026-05-06)
+- **fix**: Unbounded variable-length path queries (no LIMIT) now always route to `_bfs_stream_pages` (cursor-based `ReadBFSPage`) instead of `ReadBFSResults` (single JSON string that hits `<MAXSTRING>` at 93K+ results). Bounded queries (LIMIT present) keep `ReadBFSResults` fast path.
+- **fix**: `test_sc003_results_match_bfs` — replaced raw `NKGAccel.BFSJson` call (bypassed engine, `^NKG` stale) with engine determinism check; `knows_data` fixture calls `engine.rebuild_nkg()` for sync guarantee
+- **test**: `tests/e2e/test_streaming_bfs.py` — 3 e2e + 2 routing unit tests for streaming BFS
+
+### v1.84.0 (2026-05-06)
+- **feat**: `engine.index(name)` → `IndexHandle` (Pydantic `BaseModel`) — unified entry point for all index types (`ivf`, `bm25`, `vec`, `plaid`) via `.search()`, `.insert()`, `.info()`, `.drop()`
+- **feat**: `IVGIndex` `@runtime_checkable` Protocol — structural subtyping, no inheritance required
+- **feat**: `_build_index_registry()` — auto-populates `{name: type}` from `^IVF`, `^VecIdx`, `^BM25Idx`, `^PLAID` on `IRISGraphEngine.__init__`; updated by `*_build` methods
+- **feat**: `PLAIDSearch.Build` public ClassMethod — calls `StoreCentroids`+`StoreDocTokensBatch`+`BuildInvertedIndex` internally; helpers marked `[ Private ]`
+- **feat**: `plaid_build()` now calls `PLAIDSearch.Build` (single round-trip); `plaid_info()` returns `{"type":"plaid","indexed":N,"nlist":L,"dim":D}`
+- **feat**: All `*_info()` methods return `"type"` key — `ivf_info()`, `bm25_info()`, `vec_info()`, `plaid_info()`
+- **feat**: `IVGIndex` and `IndexHandle` exported from `iris_vector_graph.__init__`
+- **test**: Full PLAID e2e coverage (5/5); `engine.index()` dispatch tests (5 pass, 1 skip)
+
 ### v1.83.0 (2026-05-06)
 - **feat**: `KHop2Count` + `KHop2NeighborIds(maxResults)` on `Graph.KG.Traversal` — pure ObjectScript 2-hop traversal with process-private dedup, no JSON serialization
 - **feat**: `execute_cypher` routes `[:PRED*2]` COUNT and LIMIT patterns to fast paths — IC3 LIMIT 1000 now **1.2ms p50** (was 14-22ms; 3.5x faster than GES 4.19ms)

{iris_vector_graph-1.88.0 → iris_vector_graph-1.90.0}/README.md

@@ -681,6 +681,45 @@ anchors = engine.get_kg_anchors(icd_codes=["J18.0", "E11.9"])
 
  ## Changelog
 
+### v1.88.0 (2026-05-07)
+- **feat**: `ffi_kg_build_2hop_exact_int` Rust function — integer-indexed single-pass 2-hop dedup from `^KG("out")`. Writes results to `^ArnoKG("2h")` temp global; `DecodeBuildResults()` ObjectScript method converts to `^KG("deg2p_exact")`
+- **feat**: `KHop2CountExact(src, pred)` ObjectScript method — O(1) `$Get(^KG("deg2p_exact"))`, fallback to `KHop2Count` when not populated. 0.14ms p50 on SF10 (was 70ms)
+- **feat**: `Build2HopExactStats()` — Rust-first (tries `kg_build_2hop_exact_int`), ObjectScript fallback. Called automatically by `BuildNKG` and `engine.rebuild_nkg()`
+- **feat**: `engine.khop2_count_exact(node_id, pred)` — public method with `KHop2Input` validation
+- **feat**: `engine.backfill_deg2p_exact()` — populate `^KG("deg2p_exact")` for graphs loaded via `BulkIngestEdges`
+- **feat**: `execute_cypher` `[:P*2] RETURN count(n)` fast path now routes to `KHop2CountExact` (exact, not upper bound)
+- **test**: `tests/e2e/test_ic3_exact_count.py` — correctness + perf validation for 2-hop exact COUNT
+- **test**: `tests/e2e/test_untested_methods.py` — 113/113 public engine methods now have at least one test (100% coverage)
+
+### v1.87.0 (2026-05-07)
+- **feat**: `iris_vector_graph/_validate.py` — 10 Pydantic `BaseModel` input schemas for high-risk engine methods: `NodeIdInput`, `EdgeInput`, `CypherInput`, `IVFBuildInput`, `VectorSearchInput`, `BM25BuildInput`, `BM25SearchInput`, `KHop2Input`, `TemporalEdgeInput`, `VecSearchInput`
+- **feat**: Input validation at call entry on `execute_cypher`, `create_node`, `create_edge`, `ivf_build`, `ivf_search`, `bm25_build`, `bm25_search`, `khop2_count_fast`, `create_edge_temporal`, `search_nodes_by_vector`
+- All 10 schemas exported from `iris_vector_graph.__init__`; 44/44 unit tests in `test_validation.py`
+- **chore**: `BulkIngestEdges` marked `[ Internal ]` in `EdgeScan.cls` — safe path is `engine.bulk_ingest_edges()`
+
+### v1.86.0 (2026-05-07)
+- **feat**: `IVGResult` Pydantic `BaseModel` replaces `Dict[str, Any]` as return type of `execute_cypher`
+  - Backward-compatible: `result["columns"]`, `result.get("error")`, `"error" in result` all work
+  - `bool(result)` = `True` on success, `False` on error
+  - `result.columns`, `result.rows`, `result.error`, `result.metadata`, `result.sql` via dot notation
+  - 23 unit tests in `test_ivgresult.py`; all 189+ existing call sites pass unchanged
+- **feat**: Fourth Pydantic increment — `IVGResult` joins `SQLQuery`, `QueryMetadata`, `IndexHandle`
+
+### v1.85.0 (2026-05-06)
+- **fix**: Unbounded variable-length path queries (no LIMIT) now always route to `_bfs_stream_pages` (cursor-based `ReadBFSPage`) instead of `ReadBFSResults` (single JSON string that hits `<MAXSTRING>` at 93K+ results). Bounded queries (LIMIT present) keep `ReadBFSResults` fast path.
+- **fix**: `test_sc003_results_match_bfs` — replaced raw `NKGAccel.BFSJson` call (bypassed engine, `^NKG` stale) with engine determinism check; `knows_data` fixture calls `engine.rebuild_nkg()` for sync guarantee
+- **test**: `tests/e2e/test_streaming_bfs.py` — 3 e2e + 2 routing unit tests for streaming BFS
+
+### v1.84.0 (2026-05-06)
+- **feat**: `engine.index(name)` → `IndexHandle` (Pydantic `BaseModel`) — unified entry point for all index types (`ivf`, `bm25`, `vec`, `plaid`) via `.search()`, `.insert()`, `.info()`, `.drop()`
+- **feat**: `IVGIndex` `@runtime_checkable` Protocol — structural subtyping, no inheritance required
+- **feat**: `_build_index_registry()` — auto-populates `{name: type}` from `^IVF`, `^VecIdx`, `^BM25Idx`, `^PLAID` on `IRISGraphEngine.__init__`; updated by `*_build` methods
+- **feat**: `PLAIDSearch.Build` public ClassMethod — calls `StoreCentroids`+`StoreDocTokensBatch`+`BuildInvertedIndex` internally; helpers marked `[ Private ]`
+- **feat**: `plaid_build()` now calls `PLAIDSearch.Build` (single round-trip); `plaid_info()` returns `{"type":"plaid","indexed":N,"nlist":L,"dim":D}`
+- **feat**: All `*_info()` methods return `"type"` key — `ivf_info()`, `bm25_info()`, `vec_info()`, `plaid_info()`
+- **feat**: `IVGIndex` and `IndexHandle` exported from `iris_vector_graph.__init__`
+- **test**: Full PLAID e2e coverage (5/5); `engine.index()` dispatch tests (5 pass, 1 skip)
+
 ### v1.83.0 (2026-05-06)
 - **feat**: `KHop2Count` + `KHop2NeighborIds(maxResults)` on `Graph.KG.Traversal` — pure ObjectScript 2-hop traversal with process-private dedup, no JSON serialization
 - **feat**: `execute_cypher` routes `[:PRED*2]` COUNT and LIMIT patterns to fast paths — IC3 LIMIT 1000 now **1.2ms p50** (was 14-22ms; 3.5x faster than GES 4.19ms)

{iris_vector_graph-1.88.0 → iris_vector_graph-1.90.0}/iris_src/src/Graph/KG/NKGAccel.cls

@@ -559,7 +559,7 @@ ClassMethod BFSJson(seed As %String, predicatesJson As %String = "[]", maxHops A
     If '$Data(^||NKGAccel("compute_fn")) {
         Set dllid = $ZF(-4, 1, dllPath)
         If dllid = 0 {
-            Return ##class(Graph.KG.Traversal).BFSFastJson(seed, predicatesJson, maxHops, "")
+            Return ##class(Graph.KG.Traversal).BFSFastJsonSorted(seed, predicatesJson, maxHops, "", "out", maxResults)
         }
         Set ^||NKGAccel("dllid") = dllid
         Set ^||NKGAccel("compute_fn") = $ZF(-4, 3, dllid, "kg_bfs_compute")
@@ -569,11 +569,11 @@ ClassMethod BFSJson(seed As %String, predicatesJson As %String = "[]", maxHops A
     Set dllid = ^||NKGAccel("dllid")
     Set computeFn = ^||NKGAccel("compute_fn")
     If computeFn = 0 {
-        Return ##class(Graph.KG.Traversal).BFSFastJson(seed, predicatesJson, maxHops, "")
+        Return ##class(Graph.KG.Traversal).BFSFastJsonSorted(seed, predicatesJson, maxHops, "", "out", maxResults)
     }
     Do ..CacheNKGAdj()
     If '$Data(^ArnoKG("KG", "nkg_adj")) {
-        Return ##class(Graph.KG.Traversal).BFSFastJson(seed, predicatesJson, maxHops, "")
+        Return ##class(Graph.KG.Traversal).BFSFastJsonSorted(seed, predicatesJson, maxHops, "", "out", maxResults)
     }
     Kill ^ArnoKG("bfs_result")
     Set raw = $ZF(-5, dllid, computeFn, "^ArnoKG", "^ArnoKG", seed, predicatesJson, maxHops, maxResults)
@@ -583,15 +583,27 @@ ClassMethod BFSJson(seed As %String, predicatesJson As %String = "[]", maxHops A
     Set n = +$Piece(raw, ":", 3)
     Set readFn = ^||NKGAccel("read_fn")
     If readFn = 0 {
-        Return ##class(Graph.KG.Traversal).BFSFastJson(seed, predicatesJson, maxHops, "")
+        Return ##class(Graph.KG.Traversal).BFSFastJsonSorted(seed, predicatesJson, maxHops, "", "out", maxResults)
     }
-    Set result = ""
+    Set assembled = ""
     For i = 1:1:n {
-        Set chunk = $ZF(-5, dllid, readFn, "^ArnoKG", i)
-        Set result = result _ chunk
+        Set assembled = assembled _ $ZF(-5, dllid, readFn, "^ArnoKG", i)
     }
     Kill ^ArnoKG("bfs_result")
-    Return result
+    Set tag = $Job _ "_bfs"
+    Kill ^ArnoKG("bfs_r", tag)
+    Set arr = ##class(%DynamicArray).%FromJSON(assembled)
+    Set sz = arr.%Size()
+    For i = 0:1:(sz-1) {
+        Set item = arr.%Get(i)
+        Set step = +item.%Get("step")
+        Set o    = item.%Get("o")
+        Set s    = item.%Get("s")
+        Set p    = item.%Get("p")
+        Set w    = +item.%Get("w")
+        Set ^ArnoKG("bfs_r", tag, step, o) = $ListBuild(s, p, w)
+    }
+    Return "SORTED:" _ tag
 }
 
 ClassMethod InvalidateAdjCache()
@@ -1035,4 +1047,41 @@ ClassMethod CountDistinctKHop(srcId As %String, predsJson As %String = "", maxHo
     Return "{""estimate"":"_estimate_",""registers"":256,""std_error"":0.065}"
 }
 
+ClassMethod Build2HopExact() As %Boolean
+{
+    If '..IsLoaded() {
+        Do ..Load("/tmp/libarno_callout.so")
+        If '..IsLoaded() {
+            If ##class(Graph.KG.ArnoAccel).IsAvailable() {
+                Set ^||NKGAccel("dllid") = $Get(^||ArnoAccel("dllid"), 0)
+            }
+        }
+    }
+    If '..IsLoaded() Return 0
+    Set dllid = $Get(^||NKGAccel("dllid"), 0)
+    If dllid = 0 Return 0
+    Set fid = $ZF(-4, 3, dllid, "kg_build_2hop_exact_stream")
+    If fid = 0 Return 0
+    Kill ^ArnoKG("2hs")
+    Set raw = $ZF(-5, dllid, fid)
+    If $Extract(raw, 1, 8) '= "CHUNKED:" Return 0
+    Set n = +$Piece(raw, ":", 3)
+    Set data = ""
+    For i = 1:1:n {
+        Set data = data _ $Get(^ArnoKG("2hs", i), "")
+    }
+    Kill ^ArnoKG("2hs")
+    For pos = 1:1:$Length(data, $Char(10)) {
+        Set line = $Piece(data, $Char(10), pos)
+        If line = "" Continue
+        Set s    = $Piece(line, $Char(31), 1)
+        Set p    = $Piece(line, $Char(31), 2)
+        Set cnt  = +$Piece(line, $Char(31), 3)
+        If (s '= "") && (p '= "") && (cnt > 0) {
+            Set ^KG("deg2p_exact", s, p) = cnt
+        }
+    }
+    Return 1
+}
+
 }

{iris_vector_graph-1.88.0 → iris_vector_graph-1.90.0}/iris_src/src/Graph/KG/Traversal.cls

@@ -1179,15 +1179,15 @@ ClassMethod KHop2CountExact(srcId As %String, pred As %String = "") As %Integer
 ClassMethod Build2HopExactStats() As %Integer
 {
     Kill ^KG("deg2p_exact")
-    If ##class(Graph.KG.ArnoAccel).IsAvailable() {
-        Set dllid = $Get(^||ArnoAccel("dllid"), 0)
-        If dllid > 0 {
-            Set fid = $ZF(-4, 3, dllid, "kg_build_2hop_exact")
-            If fid > 0 {
-                Set result = $ZF(-5, dllid, fid)
-                Return +$Piece($Piece(result, "entries", 2), "}", 1)
-            }
+    If ##class(Graph.KG.NKGAccel).Build2HopExact() {
+        Set n = ""
+        Set cnt = 0
+        For {
+            Set n = $Order(^KG("deg2p_exact", n))
+            Quit:n=""
+            Set cnt = cnt + 1
         }
+        Return cnt
     }
     Set src = ""
     Set cnt = 0

{iris_vector_graph-1.88.0 → iris_vector_graph-1.90.0}/iris_vector_graph/engine.py

@@ -1536,12 +1536,26 @@ class IRISGraphEngine:
                     max_hops,
                     max_results,
                 )
-                bfs_results = _json.loads(str(bfs_json)) if bfs_json else []
+                bfs_str = str(bfs_json) if bfs_json else ""
+                if bfs_str.startswith("SORTED:") and bfs_str != "SORTED:0":
+                    tag = bfs_str.split(":")[1]
+                    if max_results == 0:
+                        bfs_results = list(_bfs_stream_pages(self.conn, tag))
+                    else:
+                        try:
+                            results_str = str(_call_classmethod(
+                                self.conn, "Graph.KG.Traversal", "ReadBFSResults", tag
+                            ))
+                            bfs_results = _json.loads(results_str)
+                        except Exception:
+                            bfs_results = list(_bfs_stream_pages(self.conn, tag))
+                elif bfs_str:
+                    bfs_results = _json.loads(bfs_str)
+                else:
+                    bfs_results = []
                 logger.debug("Arno BFSJson: %d results for %s", len(bfs_results), source_id)
-                if not bfs_results and not self._arno_capabilities.get("rust_callout"):
-                    bfs_results = None
             except Exception as e:
-                logger.warning(f"Arno BFSJson failed, falling back to BFSFastJson: {e}")
+                logger.warning(f"Arno BFSJson failed, falling back to BFSFastJsonSorted: {e}")
                 bfs_results = None
 
         if bfs_results is None:
@@ -1566,21 +1580,8 @@ class IRISGraphEngine:
                 else:
                     bfs_results = []
             except Exception as e:
-                logger.warning(f"BFSFastJsonSorted failed ({e}), falling back to chunked")
-                try:
-                    resp = str(_call_classmethod(
-                        self.conn, "Graph.KG.Traversal", "BFSFastJsonChunked",
-                        source_id, predicates_json, max_hops, "", direction, max_results,
-                    ))
-                    if resp.startswith("CHUNKED:") and resp != "CHUNKED:0":
-                        tag, n_chunks = resp.split(":")[1], int(resp.split(":")[2])
-                        parts = [str(_call_classmethod(self.conn, "Graph.KG.Traversal", "ReadBFSChunk", tag, str(i))) for i in range(1, n_chunks + 1)]
-                        bfs_results = _json.loads("[" + "".join(parts) + "]")
-                    else:
-                        bfs_results = []
-                except Exception as e2:
-                    logger.warning(f"BFSFastJsonChunked also failed: {e2}")
-                    return IVGResult(columns=[], rows=[], sql="", params=[], metadata=sql_query.query_metadata)
+                logger.warning(f"BFSFastJsonSorted failed: {e}")
+                return IVGResult(columns=[], rows=[], sql="", params=[], metadata=sql_query.query_metadata)
 
 
         if min_hops > 1:
@@ -3088,6 +3089,8 @@ class IRISGraphEngine:
                         registry[name_str] = type_str
         except Exception:
             pass
+        if self._probe_native_vec():
+            registry["hnsw"] = "hnsw"
         return registry
 
     def index(self, name: str) -> "IndexHandle":

{iris_vector_graph-1.88.0 → iris_vector_graph-1.90.0}/iris_vector_graph/index_protocol.py

@@ -21,30 +21,34 @@ _SEARCH = {
     "bm25":  lambda e, name, q, k, kw: e.bm25_search(name, q, k),
     "vec":   lambda e, name, q, k, kw: e.vec_search(name, q, k, **kw),
     "plaid": lambda e, name, q, k, kw: e.plaid_search(name, q, k),
+    "hnsw":  lambda e, name, q, k, kw: e.search_nodes_by_vector(q, k=k, **kw),
 }
 _INSERT = {
     "ivf":   lambda e, name, id_, vec: e.ivf_insert(name, id_, vec),
     "bm25":  lambda e, name, id_, vec: e.bm25_insert(name, id_, vec),
     "vec":   lambda e, name, id_, vec: e.vec_insert(name, id_, vec),
     "plaid": lambda e, name, id_, vec: e.plaid_insert(name, id_, vec),
+    "hnsw":  lambda e, name, id_, vec: e.store_embedding(id_, vec),
 }
 _DROP = {
     "ivf":   lambda e, name: e.ivf_drop(name),
     "bm25":  lambda e, name: e.bm25_drop(name),
     "vec":   lambda e, name: e.vec_drop(name),
     "plaid": lambda e, name: e.plaid_drop(name),
+    "hnsw":  lambda e, name: None,
 }
 _INFO = {
     "ivf":   lambda e, name: e.ivf_info(name),
     "bm25":  lambda e, name: e.bm25_info(name),
     "vec":   lambda e, name: e.vec_info(name),
     "plaid": lambda e, name: e.plaid_info(name),
+    "hnsw":  lambda e, name: {"type": "hnsw", "available": e._probe_native_vec()},
 }
 
 
 class IndexHandle(BaseModel):
     name: str = Field(min_length=1)
-    type: Literal["ivf", "bm25", "vec", "plaid"]
+    type: Literal["ivf", "bm25", "vec", "plaid", "hnsw"]
     engine: Any
 
     model_config = {"arbitrary_types_allowed": True}

{iris_vector_graph-1.88.0 → iris_vector_graph-1.90.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "iris-vector-graph"
-version = "1.88.0"
+version = "1.90.0"
 description = "Transactional Graph + Vector retrieval system for InterSystems IRIS with hybrid search, openCypher, and GraphQL APIs"
 readme = "README.md"
 license = "MIT"

iris_vector_graph-1.90.0/tests/e2e/test_arno_bfs_unified.py

@@ -0,0 +1,137 @@
+import os
+import time
+import statistics
+import pytest
+
+IRIS_HOST = os.environ.get("IRIS_HOST", "localhost")
+IRIS_ENT_PORT = int(os.environ.get("IRIS_ENT_PORT", "4972"))
+IRIS_COM_PORT = int(os.environ.get("IRIS_COM_PORT", "1972"))
+SKIP = os.environ.get("SKIP_IRIS_TESTS", "false").lower() == "true"
+PRED = "KNOWS"
+
+
+@pytest.fixture(scope="module")
+def community_engine():
+    try:
+        import iris
+        from iris_vector_graph.engine import IRISGraphEngine
+        conn = iris.connect(IRIS_HOST, IRIS_COM_PORT, "USER", "_SYSTEM", "SYS")
+        yield IRISGraphEngine(conn), iris.createIRIS(conn)
+        conn.close()
+    except Exception as e:
+        pytest.skip(f"Community IRIS unavailable: {e}")
+
+
+@pytest.fixture(scope="module")
+def enterprise_engine():
+    try:
+        import iris
+        from iris_vector_graph.engine import IRISGraphEngine
+        conn = iris.connect(IRIS_HOST, IRIS_ENT_PORT, "USER", "_SYSTEM", "SYS")
+        o = iris.createIRIS(conn)
+        o.classMethodValue("Graph.KG.ArnoAccel", "Load")
+        eng = IRISGraphEngine(conn)
+        eng._detect_arno()
+        if not eng._arno_capabilities.get("rust_callout") or \
+           "bfs" not in eng._arno_capabilities.get("rust_algorithms", []):
+            pytest.skip("Arno Rust BFS not available on enterprise container")
+        cur = conn.cursor()
+        cur.execute("SELECT TOP 1 s FROM Graph_KG.rdf_edges WHERE p = ?", [PRED])
+        row = cur.fetchone()
+        if not row:
+            pytest.skip("No KNOWS edges in enterprise — LDBC data not loaded")
+        yield eng, o, str(row[0])
+        conn.close()
+    except Exception as e:
+        pytest.skip(f"Enterprise IRIS unavailable or Rust BFS inactive: {e}")
+
+
+@pytest.fixture(scope="module")
+def bfs_test_graph(community_engine):
+    eng, o = community_engine
+    cur = eng.conn.cursor()
+    nodes = ["bfs_hub", "bfs_a", "bfs_b", "bfs_c"]
+    for n in nodes:
+        cur.execute("SELECT COUNT(*) FROM Graph_KG.nodes WHERE node_id=?", [n])
+        if cur.fetchone()[0] == 0:
+            cur.execute("INSERT INTO Graph_KG.nodes (node_id) VALUES (?)", [n])
+    eng.conn.commit()
+    from iris_vector_graph.schema import _call_classmethod
+    for s, t in [("bfs_hub", "bfs_a"), ("bfs_hub", "bfs_b"), ("bfs_a", "bfs_c")]:
+        cur.execute("SELECT COUNT(*) FROM Graph_KG.rdf_edges WHERE s=? AND p=? AND o_id=?", [s, "BFS_R", t])
+        if cur.fetchone()[0] == 0:
+            cur.execute("INSERT INTO Graph_KG.rdf_edges (s,p,o_id) VALUES (?,?,?)", [s, "BFS_R", t])
+    eng.conn.commit()
+    _call_classmethod(eng.conn, "Graph.KG.Traversal", "BuildKG")
+    yield
+    for n in nodes:
+        cur.execute("DELETE FROM Graph_KG.rdf_edges WHERE s=? OR o_id=?", [n, n])
+        cur.execute("DELETE FROM Graph_KG.nodes WHERE node_id=?", [n])
+    eng.conn.commit()
+
+
+@pytest.mark.skipif(SKIP, reason="SKIP_IRIS_TESTS=true")
+@pytest.mark.e2e
+def test_nkgaccel_bfs_json_output_format_is_sorted(enterprise_engine):
+    eng, o, seed = enterprise_engine
+    result = str(o.classMethodString("Graph.KG.NKGAccel", "BFSJson", seed, '["KNOWS"]', 2, 100))
+    assert result.startswith("SORTED:"), \
+        f"NKGAccel.BFSJson must return 'SORTED:tag' after spec 153, got: {result[:40]}"
+
+
+@pytest.mark.skipif(SKIP, reason="SKIP_IRIS_TESTS=true")
+@pytest.mark.e2e
+def test_rust_bfs_result_matches_objectscript(enterprise_engine):
+    eng, o, seed = enterprise_engine
+    from iris_vector_graph.schema import _call_classmethod_large
+    import json
+
+    rust_raw = str(o.classMethodString("Graph.KG.NKGAccel", "BFSJson", seed, '["KNOWS"]', 2, 0))
+    if rust_raw.startswith("SORTED:"):
+        tag = rust_raw.split(":")[1]
+        rust_results = json.loads(str(o.classMethodString("Graph.KG.Traversal", "ReadBFSResults", tag)))
+    else:
+        rust_results = json.loads(rust_raw)
+
+    obj_results = json.loads(_call_classmethod_large(o, "Graph.KG.Traversal", "BFSFastJson", seed, "KNOWS", 2))
+    assert len(rust_results) > 0
+    assert abs(len(rust_results) - len(obj_results)) <= 1, \
+        f"Rust ({len(rust_results)}) and ObjectScript ({len(obj_results)}) BFS counts differ by >1"
+
+
+@pytest.mark.skipif(SKIP, reason="SKIP_IRIS_TESTS=true")
+@pytest.mark.e2e
+def test_engine_execute_cypher_bfs_via_rust(enterprise_engine):
+    eng, o, seed = enterprise_engine
+    result = eng.execute_cypher(
+        "MATCH (s {node_id:$id})-[:KNOWS*1..2]->(n) RETURN n.node_id LIMIT 100",
+        {"id": seed}
+    )
+    assert result, "execute_cypher must succeed"
+    assert len(result.rows) > 0, "Must return results"
+    assert len(result.rows) <= 100
+
+
+@pytest.mark.skipif(SKIP, reason="SKIP_IRIS_TESTS=true")
+@pytest.mark.e2e
+def test_engine_chunked_branch_removed():
+    import iris_vector_graph.engine as eng_mod
+    import inspect
+    src = inspect.getsource(eng_mod.IRISGraphEngine._execute_var_length_cypher)
+    assert "BFSFastJsonChunked" not in src, \
+        "Legacy BFSFastJsonChunked branch must be removed from _execute_var_length_cypher"
+
+
+@pytest.mark.skipif(SKIP, reason="SKIP_IRIS_TESTS=true")
+@pytest.mark.e2e
+def test_objectscript_bfs_still_works_after_change(community_engine, bfs_test_graph):
+    eng, o = community_engine
+    result = eng.execute_cypher(
+        "MATCH (s {node_id:$id})-[:BFS_R*1..2]->(n) RETURN n.node_id",
+        {"id": "bfs_hub"}
+    )
+    assert result
+    ids = {r[0] for r in result.rows}
+    assert "bfs_a" in ids
+    assert "bfs_b" in ids
+    assert "bfs_c" in ids