iris-vector-graph 2.3.0__tar.gz → 2.3.1__tar.gz

{iris_vector_graph-2.3.0 → iris_vector_graph-2.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iris-vector-graph
-Version: 2.3.0
+Version: 2.3.1
 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

{iris_vector_graph-2.3.0 → iris_vector_graph-2.3.1}/iris_src/src/Graph/KG/EdgeScan.cls

@@ -1,3 +1,27 @@
+/// Graph.KG.EdgeScan — adjacency-global maintenance + scan procedures.
+///
+/// ============================================================================
+/// ^KG ADJACENCY LAYOUT OF RECORD (canonical — do not deviate)
+/// ============================================================================
+/// The production adjacency layout is SHARD-PREFIXED:
+///
+///     ^KG("out", 0, s, p, o) = weight     outbound edges
+///     ^KG("in",  0, o, p, s) = weight     inbound edges
+///     ^KG("deg", s)          = out-degree
+///     ^KG("degp", s, p)      = per-predicate out-degree
+///
+/// Every live reader scans this layout: MatchEdges (here), Graph.KG.Algorithms,
+/// Graph.KG.Centrality, Graph.KG.Subgraph, and the NKG builders. WriteAdjacency
+/// (below), TraversalBuild.BuildKG, TemporalIndex.InsertEdge, and the (currently
+/// undeployed) Graph.KG.GraphIndex functional index all WRITE this exact form.
+///
+/// There is a LEGACY no-shard layout — ^KG("out", s, p, o) — still written by
+/// the bench harness (Graph.KG.BenchSeeder / BenchFormat) and the standalone CSV
+/// Graph.KG.Loader, and read by dead Else-fallback branches in NKGAccelTraversal
+/// / NKGAccelAdjacency. Nothing in the production write/read path uses it.
+/// DO NOT add new readers or writers of the no-shard form. If you need adjacency,
+/// use ^KG("out", 0, ...). See docs/index-maintenance-architecture-review.md.
+/// ============================================================================
 Class Graph.KG.EdgeScan Extends %RegisteredObject
 {
 

{iris_vector_graph-2.3.0 → iris_vector_graph-2.3.1}/iris_src/src/Graph/KG/GraphIndex.cls

@@ -62,8 +62,12 @@ ClassMethod InsertIndex(pID As %String, s As %Binary, p As %Binary, o As %Binary
 {
 	Set weight = ##class(Graph.KG.GraphIndex).ExtractWeight(qualifiers)
 
-	Set ^KG("out", s, p, o) = weight
-	Set ^KG("in", o, p, s) = weight
+	// Shard-0 layout — MUST match EdgeScan.WriteAdjacency / TraversalBuild.BuildKG.
+	// Every live reader (MatchEdges, Algorithms, Centrality, NKG BFS) scans
+	// ^KG("out", 0, ...). Writing the legacy no-shard layout here would populate
+	// globals nothing reads. See Graph.KG.EdgeScan:WriteAdjacency for the canonical form.
+	Set ^KG("out", 0, s, p, o) = weight
+	Set ^KG("in", 0, o, p, s) = weight
 	Set tmp = $Increment(^KG("deg", s))
 	Set tmp = $Increment(^KG("degp", s, p))
 
@@ -147,8 +151,8 @@ ClassMethod UpdateIndex(pID As %String, s As %Binary, p As %Binary, o As %Binary
 
 ClassMethod DeleteIndex(pID As %String, s As %Binary, p As %Binary, o As %Binary, qualifiers As %Binary = "") As %Status [ ServerOnly = 1 ]
 {
-	Kill ^KG("out", s, p, o)
-	Kill ^KG("in", o, p, s)
+	Kill ^KG("out", 0, s, p, o)
+	Kill ^KG("in", 0, o, p, s)
 	Set tmp = $Increment(^KG("deg", s), -1)
 	Set tmp = $Increment(^KG("degp", s, p), -1)
 	If $Get(^KG("deg", s)) <= 0 Kill ^KG("deg", s)

{iris_vector_graph-2.3.0 → iris_vector_graph-2.3.1}/iris_src/src/Graph/KG/Loader.cls

@@ -1,4 +1,11 @@
-/// Fast CSV loader for Graph data
+/// Fast CSV loader for Graph data.
+///
+/// WARNING — LEGACY NO-SHARD LAYOUT. This loader writes ^KG("out", s, p, o)
+/// (no shard prefix), which is NOT the production layout. Live readers scan
+/// ^KG("out", 0, s, p, o) (see Graph.KG.EdgeScan for the layout of record), so
+/// data loaded here is invisible to BFS / centrality / Cypher. It has no callers
+/// in the engine. Prefer engine.bulk_load_session() / bulk_create_edges(). If you
+/// must use this, run engine.sync() afterward to rebuild the shard-0 globals.
 Class Graph.KG.Loader Extends %RegisteredObject
 {
 

{iris_vector_graph-2.3.0 → iris_vector_graph-2.3.1}/iris_src/src/Graph/KG/NKGAccelAdjacency.cls

@@ -1,3 +1,10 @@
+/// NKG-accelerated adjacency lookups over the interned ^NKG index.
+///
+/// NOTE: the ^KG fallback branches read the LEGACY no-shard
+/// ^KG("out", node, ...) layout, NOT the production shard-0 layout
+/// (^KG("out", 0, ...) — see Graph.KG.EdgeScan for the layout of record).
+/// They are dead in production (UseNKG() is true after any sync()). Fix them to
+/// the shard-0 layout before relying on them.
 Class Graph.KG.NKGAccelAdjacency Extends %RegisteredObject
 {
 

{iris_vector_graph-2.3.0 → iris_vector_graph-2.3.1}/iris_src/src/Graph/KG/NKGAccelTraversal.cls

@@ -1,3 +1,11 @@
+/// NKG-accelerated traversal (K-hop, BFS) over the interned ^NKG index.
+///
+/// NOTE: the `If useNKG { ^NKG... } Else { ^KG... }` fallback branches read the
+/// LEGACY no-shard ^KG("out", node, pred, dst) layout, NOT the production
+/// shard-0 layout (^KG("out", 0, ...) — see Graph.KG.EdgeScan for the layout of
+/// record). These Else branches are effectively dead in production: UseNKG()
+/// returns true whenever ^NKG("$meta") exists, which is true after any sync().
+/// If you ever make them reachable, fix them to scan the shard-0 layout first.
 Class Graph.KG.NKGAccelTraversal Extends %RegisteredObject
 {
 

{iris_vector_graph-2.3.0 → iris_vector_graph-2.3.1}/iris_vector_graph/_engine/admin.py

@@ -305,6 +305,99 @@ class AdminMixin:
                        "^NKG_populated": adjacency.nkg_populated} if internals else None,
         )
 
+    def verify_sync(self, heal: bool = False) -> "SyncReport":
+        """Check whether the ^KG/^NKG adjacency indexes agree with the SQL tables.
+
+        The authoritative graph state lives in ``Graph_KG.rdf_edges``. The ^KG/^NKG
+        globals are a derived acceleration index, maintained inline by
+        ``create_edge`` / ``bulk_*`` / ``WriteAdjacency`` but NOT by every write
+        path. BYPASS paths — ``drop_graph``, ``delete_node``, raw SQL inserts, the
+        ``map_sql_table`` bridge, or an interrupted bulk load — mutate the table
+        without touching the globals, leaving BFS / centrality / var-length Cypher
+        silently stale. This compares the SQL edge count against the ^NKG edge
+        count and reports the divergence.
+
+        Args:
+            heal: When True, run ``sync()`` to rebuild the globals if drift is found.
+
+        Returns:
+            SyncReport. ``report.in_sync`` is False when counts diverge OR the
+            in-process ``_nkg_dirty`` flag is set. ``bool(report)`` mirrors
+            ``in_sync`` for ``if not engine.verify_sync(): engine.sync()`` usage.
+        """
+        from iris_vector_graph.status import SyncReport
+
+        sql_edges = 0
+        global_edges = 0
+        global_nodes = 0
+        detail = None
+        indeterminate = False
+
+        cursor = self.conn.cursor()
+        try:
+            cursor.execute(f"SELECT COUNT(*) FROM {_table('rdf_edges')}")
+            row = cursor.fetchone()
+            sql_edges = int(row[0]) if row else 0
+        except Exception as e:
+            indeterminate = True
+            detail = f"SQL edge count failed: {str(e)[:120]}"
+
+        try:
+            iris_obj = self._iris_obj()
+            global_edges = int(iris_obj.classMethodValue("Graph.KG.Traversal", "NKGEdgeCount"))
+            global_nodes = int(iris_obj.classMethodValue("Graph.KG.Traversal", "NKGNodeCount"))
+        except Exception as e:
+            indeterminate = True
+            detail = f"NKG count failed (globals likely unbuilt): {str(e)[:120]}"
+
+        pending = bool(getattr(self, "_nkg_dirty", False))
+
+        # Drift oracle. ``_nkg_dirty`` is the authoritative in-process signal: a
+        # write path that bypassed adjacency maintenance set it. The count
+        # comparison is a SECONDARY heuristic and is deliberately one-directional:
+        # we only flag drift when SQL edges *exceed* indexed edges (the
+        # unambiguous "rows exist in the table but not in the index" case).
+        #
+        # We do NOT flag the reverse (globals > SQL), because ^NKG's meta
+        # edgeCount is known to over-count: InternNode/InternLabel are
+        # append-only (never decremented on delete) and NKG interning ignores
+        # graph_id while the SQL UNIQUE is on (s,p,o,graph_id). Treating
+        # globals>SQL as drift would produce false positives on any DB that has
+        # seen deletes. A full rebuild (sync()) is the only way to reconcile
+        # the meta counter, and verify_sync(heal=True) does exactly that.
+        sql_exceeds = sql_edges > global_edges
+        in_sync = (not sql_exceeds) and (not pending) and (not indeterminate)
+
+        if not in_sync and detail is None:
+            if pending and not sql_exceeds:
+                detail = "pending_sync flag set — writes occurred without sync()"
+            else:
+                detail = (
+                    f"drift: {sql_edges} SQL edges vs {global_edges} indexed edges. "
+                    "A write path bypassed adjacency maintenance — call engine.sync()."
+                )
+
+        report = SyncReport(
+            in_sync=in_sync,
+            sql_edges=sql_edges,
+            global_edges=global_edges,
+            global_nodes=global_nodes,
+            pending_sync=pending,
+            healed=False,
+            detail=detail,
+        )
+
+        if heal and not in_sync:
+            try:
+                self.sync()
+                report.healed = True
+                report.in_sync = True
+                report.detail = (detail or "") + " | healed via sync()"
+            except Exception as e:
+                report.detail = (detail or "") + f" | heal failed: {str(e)[:120]}"
+
+        return report
+
     def list_active_queries(self, limit: int = 50) -> List[Dict[str, Any]]:
         """Return active IRIS SQL queries.
 

{iris_vector_graph-2.3.0 → iris_vector_graph-2.3.1}/iris_vector_graph/_engine/fhir.py

@@ -74,6 +74,21 @@ class FhirMixin:
     def map_sql_table(
         self, table: str, id_column: str, label: str, property_columns=None
     ) -> dict:
+        """Map an existing SQL table to a graph label as a read-only projection.
+
+        Cypher queries against ``label`` are translated to JOINs on ``table`` at
+        query time — rows are never copied into rdf_edges/nodes.
+
+        ADJACENCY CONTRACT: because the rows are not materialized into
+        ``Graph_KG.rdf_edges``, edges reached through this mapping (or via
+        ``map_sql_relationship``) are NOT present in the ^KG/^NKG adjacency
+        globals. Property/pattern Cypher sees them; the global-backed algorithms
+        do NOT — BFS, centrality, var-length paths, and the NKG-accelerated
+        traversals will not traverse projected edges. There is no automatic
+        propagation and ``verify_sync()`` cannot see this gap (nothing was
+        written to rdf_edges). If you need these edges in graph algorithms,
+        materialize them (create_edge / bulk_create_edges) rather than mapping.
+        """
         from iris_vector_graph.security import sanitize_identifier
 
         sanitize_identifier(table)

{iris_vector_graph-2.3.0 → iris_vector_graph-2.3.1}/iris_vector_graph/_engine/nodes_edges.py

@@ -569,6 +569,11 @@ class NodesEdgesMixin:
             self.conn.commit()
         except Exception:
             pass
+        # BYPASS: this deletes SQL rows without touching ^KG/^NKG. Flag the
+        # adjacency index as stale so var-length Cypher guards and verify_sync()
+        # surface the drift; caller should sync() to repair.
+        if deleted:
+            self._nkg_dirty = True
         return deleted
 
 
@@ -881,6 +886,9 @@ class NodesEdgesMixin:
                 f"DELETE FROM {_table('nodes')} WHERE node_id = ?", [node_id]
             )
             self.conn.commit()
+            # BYPASS: edge rows removed from SQL but ^KG/^NKG still hold them.
+            # Flag stale so var-length guards / verify_sync() catch the drift.
+            self._nkg_dirty = True
             return True
         except Exception as e:
             logger.warning(f"delete_node({node_id}) failed: {e}")
@@ -919,6 +927,9 @@ class NodesEdgesMixin:
                 logger.warning(f"bulk_delete_nodes batch failed: {e}")
             finally:
                 cursor.close()
+        # BYPASS: SQL edge rows removed without ^KG/^NKG maintenance.
+        if deleted:
+            self._nkg_dirty = True
         return deleted
 
 

{iris_vector_graph-2.3.0 → iris_vector_graph-2.3.1}/iris_vector_graph/_engine/temporal.py

@@ -22,6 +22,17 @@ class TemporalMixin:
         upsert: bool = False,
         graph: Optional[str] = None,
     ) -> bool:
+        """Create a timestamped edge in the temporal index.
+
+        ADJACENCY CONTRACT: TemporalIndex.InsertEdge writes the temporal globals
+        (^KG "tout"/"tin"/buckets/aggregates) AND a shadow ^KG("out",0,...)
+        adjacency entry — so temporal edges ARE visible to the ^KG-based readers
+        (MatchEdges, Algorithms, Centrality). They are NOT written to the
+        interned ^NKG(-1,...) index, so the NKG-accelerated (arno/Rust) BFS path
+        will not see them until a BuildNKG. Call engine.sync() if you need
+        temporal edges in NKG-accelerated traversals. Edges are only mirrored
+        into the rdf_edges SQL table when ``graph=`` is supplied.
+        """
         if timestamp is not None:
             TemporalEdgeInput(source=source, predicate=predicate, target=target,
                               timestamp=int(timestamp), weight=weight)

{iris_vector_graph-2.3.0 → iris_vector_graph-2.3.1}/iris_vector_graph/status.py

@@ -46,6 +46,40 @@ class IndexInventory:
     plaid_indexes: List[str] = field(default_factory=list)
 
 
+@dataclass
+class SyncReport:
+    """Result of engine.verify_sync() — quantitative ^KG/^NKG drift check.
+
+    Compares the authoritative SQL edge count (Graph_KG.rdf_edges) against the
+    adjacency-global edge count (^NKG "$meta" edgeCount). Divergence means a
+    write path bypassed global maintenance (drop_graph, delete_node, raw SQL,
+    the SQL table bridge, or an interrupted bulk load) and the acceleration
+    indexes are stale. ``pending_sync`` reflects the in-process _nkg_dirty flag.
+    """
+
+    in_sync: bool = True
+    sql_edges: int = 0
+    global_edges: int = 0
+    global_nodes: int = 0
+    pending_sync: bool = False
+    healed: bool = False
+    detail: Optional[str] = None
+
+    def __bool__(self) -> bool:
+        return self.in_sync
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "in_sync": self.in_sync,
+            "sql_edges": self.sql_edges,
+            "global_edges": self.global_edges,
+            "global_nodes": self.global_nodes,
+            "pending_sync": self.pending_sync,
+            "healed": self.healed,
+            "detail": self.detail,
+        }
+
+
 @dataclass
 class EngineStatus:
     tables: TableCounts = field(default_factory=TableCounts)

{iris_vector_graph-2.3.0 → iris_vector_graph-2.3.1}/pyproject.toml

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

iris_vector_graph-2.3.1/tests/integration/test_index_consistency_e2e.py

@@ -0,0 +1,150 @@
+"""E2E: the ^KG/^NKG-vs-SQL consistency invariant.
+
+This is the test the suite was missing. The existing index tests assert that
+sync() *calls* its sub-methods (mock-level plumbing); none assert that after a
+write the globals actually agree with the SQL tables. These tests exercise the
+real invariant on a live container:
+
+  1. A normal write (create_edge) keeps globals and SQL in sync.
+  2. A BYPASS write (raw SQL INSERT) drifts — and verify_sync() catches it.
+  3. verify_sync(heal=True) repairs the drift via sync().
+
+Requires live IRIS (iris_vector_graph community container).
+"""
+from __future__ import annotations
+
+import os
+import uuid
+
+import pytest
+
+SKIP_IRIS_TESTS = os.environ.get("SKIP_IRIS_TESTS", "false").lower() == "true"
+
+
+@pytest.mark.skipif(SKIP_IRIS_TESTS, reason="SKIP_IRIS_TESTS=true")
+class TestIndexConsistencyInvariant:
+
+    @pytest.fixture(autouse=True)
+    def setup(self, iris_connection):
+        from iris_vector_graph.engine import IRISGraphEngine
+        self.conn = iris_connection
+        self.engine = IRISGraphEngine(iris_connection, embedding_dimension=4)
+        self.run = uuid.uuid4().hex[:8]
+        self.prefix = f"drift_{self.run}"
+        yield
+        cur = iris_connection.cursor()
+        try:
+            cur.execute(f"DELETE FROM Graph_KG.rdf_edges WHERE s LIKE '{self.prefix}%'")
+            cur.execute(f"DELETE FROM Graph_KG.rdf_edges WHERE o_id LIKE '{self.prefix}%'")
+            cur.execute(f"DELETE FROM Graph_KG.nodes WHERE node_id LIKE '{self.prefix}%'")
+            iris_connection.commit()
+        except Exception:
+            pass
+        finally:
+            cur.close()
+
+    def _n(self, i):
+        return f"{self.prefix}_n{i}"
+
+    # NOTE: assertions are delta-based, not absolute. The shared enterprise DB
+    # may already carry drift from other suites/benchmarks (we observed
+    # NKG edgeCount=110 vs SQL=108 on a live container — the very drift this
+    # detector exists to catch). Absolute COUNT equality is therefore unsafe;
+    # we measure how the SQL-vs-global gap *changes* across an operation.
+
+    def _raw_insert(self, n):
+        """Insert n genuinely-new edge rows via raw SQL (bypassing create_edge).
+
+        Uses run-unique subjects so the UNIQUE (s,p,o_id) constraint never
+        silently swallows the insert in a shared/polluted DB. Returns rows added.
+        """
+        # rdf_edges has a FOREIGN KEY to nodes(node_id) — the endpoints must
+        # exist first, or the INSERT fails with SQLCODE -121. (This FK is itself
+        # the SQL layer's only built-in guard against orphan edges.)
+        cur = self.conn.cursor()
+        added = 0
+        for i in range(n):
+            s, o = f"{self.prefix}_raw{i}", f"{self.prefix}_rawtgt{i}"
+            for nid in (s, o):
+                cur.execute(
+                    "INSERT INTO Graph_KG.nodes (node_id) SELECT ? "
+                    "WHERE NOT EXISTS (SELECT 1 FROM Graph_KG.nodes WHERE node_id=?)",
+                    [nid, nid],
+                )
+            cur.execute(
+                "INSERT INTO Graph_KG.rdf_edges (s, p, o_id) VALUES (?, ?, ?)",
+                [s, "BYPASS", o],
+            )
+            added += cur.rowcount if cur.rowcount is not None else 1
+        self.conn.commit()
+        cur.close()
+        return added
+
+    def test_normal_write_then_sync_is_in_sync(self):
+        """create_edge + sync() leaves the index covering every SQL edge."""
+        for i in range(4):
+            self.engine.create_node(self._n(i), labels=["Node"])
+        for i in range(3):
+            self.engine.create_edge(self._n(i), "LINK", self._n(i + 1))
+        self.engine.sync()
+
+        after = self.engine.verify_sync()
+        # Self-maintaining writes + sync: globals cover SQL, flag is clear.
+        assert after.global_edges >= after.sql_edges
+        assert after.pending_sync is False
+        assert after.in_sync is True
+
+    def test_raw_sql_bypass_widens_the_gap(self):
+        """A raw SQL INSERT (SQL-bridge / external-ETL pattern) drifts the index."""
+        for i in range(4):
+            self.engine.create_node(self._n(i), labels=["Node"])
+        self.engine.sync()
+        before = self.engine.verify_sync()
+
+        # Bypass create_edge entirely — write the table directly.
+        added = self._raw_insert(3)
+        assert added == 3, "raw insert must add genuinely-new rows for this test"
+
+        after = self.engine.verify_sync()
+        # SQL grew by 3; globals did not → the gap widened by exactly 3.
+        assert (after.sql_edges - after.global_edges) == \
+               (before.sql_edges - before.global_edges) + 3
+        assert after.in_sync is False
+
+    def test_heal_repairs_drift(self):
+        """verify_sync(heal=True) rebuilds globals so the gap closes to zero."""
+        for i in range(4):
+            self.engine.create_node(self._n(i), labels=["Node"])
+        self.engine.create_edge(self._n(0), "LINK", self._n(1))
+        self.engine.sync()
+
+        # Introduce a known bypass drift, then confirm the detector sees a gap.
+        added = self._raw_insert(2)
+        assert added == 2
+        drifted = self.engine.verify_sync()
+        assert drifted.sql_edges > drifted.global_edges
+        assert drifted.in_sync is False
+
+        # heal=True runs a full BuildKG/BuildNKG rebuild from SQL.
+        healed = self.engine.verify_sync(heal=True)
+        assert healed.healed is True
+        # Post-rebuild every SQL edge is indexed (globals no longer trail SQL).
+        # We assert globals >= SQL rather than exact equality: ^NKG's meta
+        # edgeCount over-counts on a DB that has seen deletes (documented in
+        # verify_sync). The contract that matters — no SQL edge missing from the
+        # index — holds.
+        post = self.engine.verify_sync()
+        assert post.global_edges >= post.sql_edges
+        assert post.in_sync is True
+
+    def test_drop_graph_flags_dirty(self):
+        """drop_graph is a BYPASS — it must mark the index stale."""
+        g = f"urn:graph:{self.prefix}"
+        self.engine.create_node(self._n(0), labels=["Node"])
+        self.engine.create_node(self._n(1), labels=["Node"])
+        self.engine.create_edge(self._n(0), "LINK", self._n(1), graph=g)
+        self.engine.sync()
+
+        self.engine.drop_graph(g)
+        # The in-process dirty flag must now be set even before a count check.
+        assert self.engine._nkg_dirty is True

iris_vector_graph-2.3.1/tests/unit/test_drift_detector.py

@@ -0,0 +1,146 @@
+"""Unit tests for the index drift detector (verify_sync / check_drift).
+
+The drift detector closes the gap that the binary _nkg_dirty flag misses:
+BYPASS write paths (drop_graph, delete_node, raw SQL, the SQL table bridge)
+never set _nkg_dirty, so var-length Cypher silently runs on a stale ^KG/^NKG.
+verify_sync() compares the SQL row count of rdf_edges against the global edge
+count and reports (or, when heal=True, repairs via sync()) the divergence.
+
+These tests are mock-only — they assert the comparison logic and the public
+contract. The live consistency invariant is exercised in the E2E suite.
+"""
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+
+def _make_engine(sql_edges=0, nkg_nodes=0, nkg_edges=0):
+    from iris_vector_graph.engine import IRISGraphEngine
+
+    cursor = MagicMock()
+    cursor.fetchone.return_value = (sql_edges,)
+    conn = MagicMock()
+    conn.cursor.return_value = cursor
+
+    engine = IRISGraphEngine.__new__(IRISGraphEngine)
+    engine.conn = conn
+    engine._schema_prefix = "Graph_KG"
+    engine.embedding_dimension = 4
+    engine._nkg_dirty = False
+    engine._store = MagicMock()
+
+    iris_obj = MagicMock()
+
+    def _classmethodvalue(cls, method, *args):
+        if method == "NKGNodeCount":
+            return nkg_nodes
+        if method == "NKGEdgeCount":
+            return nkg_edges
+        return 0
+
+    iris_obj.classMethodValue.side_effect = _classmethodvalue
+    engine._iris_obj = MagicMock(return_value=iris_obj)
+    return engine, cursor
+
+
+class TestVerifySyncContract:
+
+    def test_verify_sync_exists(self):
+        engine, _ = _make_engine()
+        assert hasattr(engine, "verify_sync")
+        assert callable(engine.verify_sync)
+
+    def test_returns_report_dataclass(self):
+        engine, _ = _make_engine(sql_edges=10, nkg_edges=10)
+        report = engine.verify_sync()
+        assert hasattr(report, "in_sync")
+        assert hasattr(report, "sql_edges")
+        assert hasattr(report, "global_edges")
+
+    def test_clean_when_counts_match(self):
+        engine, _ = _make_engine(sql_edges=42, nkg_nodes=20, nkg_edges=42)
+        report = engine.verify_sync()
+        assert report.in_sync is True
+        assert bool(report) is True
+
+    def test_drift_when_sql_exceeds_globals(self):
+        # 100 edges in SQL, only 42 in ^NKG → a BYPASS path wrote SQL only.
+        engine, _ = _make_engine(sql_edges=100, nkg_nodes=20, nkg_edges=42)
+        report = engine.verify_sync()
+        assert report.in_sync is False
+        assert bool(report) is False
+        assert report.sql_edges == 100
+        assert report.global_edges == 42
+
+    def test_globals_exceeding_sql_is_not_flagged_by_counts_alone(self):
+        # globals > SQL is NOT treated as count-drift: ^NKG meta edgeCount
+        # over-counts (append-only interning, graph_id-agnostic). The dirty flag
+        # is the signal for the delete case, not the count comparison. Here the
+        # flag is clean, so by counts alone this is considered in sync.
+        engine, _ = _make_engine(sql_edges=10, nkg_nodes=20, nkg_edges=42)
+        report = engine.verify_sync()
+        assert report.in_sync is True
+
+    def test_delete_drift_caught_via_dirty_flag(self):
+        # drop_graph/delete_node set _nkg_dirty — THAT is how the delete-side
+        # drift is surfaced (globals>SQL counts are unreliable, see above).
+        engine, _ = _make_engine(sql_edges=10, nkg_edges=42)
+        engine._nkg_dirty = True
+        report = engine.verify_sync()
+        assert report.in_sync is False
+        assert report.pending_sync is True
+
+    def test_dirty_flag_forces_drift_even_if_counts_match(self):
+        # _nkg_dirty is the in-process "you wrote but didn't sync" signal.
+        engine, _ = _make_engine(sql_edges=10, nkg_edges=10)
+        engine._nkg_dirty = True
+        report = engine.verify_sync()
+        assert report.in_sync is False
+        assert report.pending_sync is True
+
+    def test_empty_graph_is_in_sync(self):
+        engine, _ = _make_engine(sql_edges=0, nkg_nodes=0, nkg_edges=0)
+        report = engine.verify_sync()
+        assert report.in_sync is True
+
+
+class TestVerifySyncHeal:
+
+    def test_heal_calls_sync_when_drifted(self):
+        engine, _ = _make_engine(sql_edges=100, nkg_edges=42)
+        with patch.object(engine, "sync", return_value=True) as mock_sync:
+            report = engine.verify_sync(heal=True)
+        mock_sync.assert_called_once()
+        assert report.healed is True
+
+    def test_heal_skips_sync_when_clean(self):
+        engine, _ = _make_engine(sql_edges=10, nkg_edges=10)
+        with patch.object(engine, "sync", return_value=True) as mock_sync:
+            report = engine.verify_sync(heal=True)
+        mock_sync.assert_not_called()
+        assert report.healed is False
+
+    def test_heal_false_by_default_does_not_sync(self):
+        engine, _ = _make_engine(sql_edges=100, nkg_edges=42)
+        with patch.object(engine, "sync", return_value=True) as mock_sync:
+            engine.verify_sync()
+        mock_sync.assert_not_called()
+
+
+class TestVerifySyncResilience:
+
+    def test_returns_report_on_global_count_error(self):
+        engine, _ = _make_engine(sql_edges=10)
+        engine._iris_obj.return_value.classMethodValue.side_effect = Exception("NKG missing")
+        # Should not raise — report the indeterminate state.
+        report = engine.verify_sync()
+        assert report is not None
+        assert report.in_sync is False
+
+    def test_to_dict_is_serializable(self):
+        import json
+        engine, _ = _make_engine(sql_edges=100, nkg_edges=42)
+        report = engine.verify_sync()
+        json.dumps(report.to_dict())