iris-vector-graph 2.4.1__tar.gz → 2.4.2__tar.gz

{iris_vector_graph-2.4.1 → iris_vector_graph-2.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iris-vector-graph
-Version: 2.4.1
+Version: 2.4.2
 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.4.1 → iris_vector_graph-2.4.2}/iris_vector_graph/_engine/nodes_edges.py

@@ -459,7 +459,11 @@ class NodesEdgesMixin:
             graph: Optional named graph identifier.
 
         Returns:
-            True if the edge was created or already existed, False on error.
+            True if a NEW edge was created. False if the edge already existed
+            (UNIQUE violation, swallowed safely) OR on error. The duplicate case is
+            safe and never raises — but it is NOT distinguishable from an error by the
+            return value, so callers that re-create edges defensively should call
+            create_edge unconditionally and not gate success on the return value.
         """
         EdgeInput(source_id=source_id, predicate=predicate, target_id=target_id)
         cursor = self.conn.cursor()

{iris_vector_graph-2.4.1 → iris_vector_graph-2.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "iris-vector-graph"
-version = "2.4.1"
+version = "2.4.2"
 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.4.1 → iris_vector_graph-2.4.2}/tests/TESTING.md

@@ -20,22 +20,22 @@ pytest -m performance
 
 The `iris_test_container` fixture (session scope) manages the container lifecycle:
 
-1. **Attach or Start**: If a container named `iris-vector-graph-main` is already running, attaches to it via `IRISContainer.attach()`. Otherwise starts a fresh container.
-2. **Ready**: Waits for the IRIS SuperServer to be ready (180s timeout).
-3. **Initialize**: Automatically creates the `Graph_KG` schema, tables, views, and loads ObjectScript classes.
-4. **Security**: Creates a dedicated **`test`** user with password **`test`** and ensures password expiry is disabled.
-5. **Verify**: Blocks until a real `test`/`test` connection succeeds — no test module ever races on a not-yet-ready container.
-6. **Execute**: Runs the requested tests.
-7. **Tear down**: Stops containers that were started by the fixture; leaves pre-existing containers running.
+1.  **Attach or Start**: If a container named `iris-vector-graph-main` is already running, attaches to it via `IRISContainer.attach()`. Otherwise starts a fresh container.
+2.  **Ready**: Waits for the IRIS SuperServer to be ready (180s timeout).
+3.  **Initialize**: Automatically creates the `Graph_KG` schema, tables, views, and loads ObjectScript classes.
+4.  **Security**: Creates a dedicated **`test`** user with password **`test`** and ensures password expiry is disabled.
+5.  **Verify**: Blocks until a real `test`/`test` connection succeeds — no test module ever races on a not-yet-ready container.
+6.  **Execute**: Runs the requested tests.
+7.  **Tear down**: Stops containers that were started by the fixture; leaves pre-existing containers running.
 
 ## Key Fixtures
 
-| Fixture               | Scope    | Description                                                                                    |
-| --------------------- | -------- | ---------------------------------------------------------------------------------------------- |
-| `iris_test_container` | Session  | Managed IRIS container for the entire test session.                                            |
-| `iris_connection`     | Module   | Reusable DBAPI connection from the managed container.                                          |
-| `iris_cursor`         | Function | Fresh cursor with automatic rollback isolation.                                                |
-| `clean_test_data`     | Function | Provides a unique prefix (e.g., `TEST_abc123:`) and auto-deletes matching data after the test. |
+| Fixture | Scope | Description |
+|---------|-------|-------------|
+| `iris_test_container` | Session | Managed IRIS container for the entire test session. |
+| `iris_connection` | Module | Reusable DBAPI connection from the managed container. |
+| `iris_cursor` | Function | Fresh cursor with automatic rollback isolation. |
+| `clean_test_data` | Function | Provides a unique prefix (e.g., `TEST_abc123:`) and auto-deletes matching data after the test. |
 
 ## Writing New Tests
 
@@ -49,64 +49,55 @@ def test_my_feature(iris_connection, clean_test_data):
     """Test with managed container and auto-cleanup."""
     prefix = clean_test_data
     cursor = iris_connection.cursor()
-
+    
     # Create test data using the unique prefix
     cursor.execute(
         "INSERT INTO nodes (node_id) VALUES (?)",
         (f"{prefix}node1",)
     )
     iris_connection.commit()
-
+    
     # Assertions
     cursor.execute("SELECT COUNT(*) FROM nodes WHERE node_id LIKE ?", (f"{prefix}%",))
     assert cursor.fetchone()[0] == 1
-
+    
     # No need to manual cleanup - clean_test_data fixture handles it!
 ```
 
 ## Configuration
 
-| Environment Variable | Default | Description                 |
-| -------------------- | ------- | --------------------------- |
-| `IRIS_TEST_TIMEOUT`  | `180`   | Startup timeout in seconds. |
+| Environment Variable | Default | Description |
+|----------------------|---------|-------------|
+| `IRIS_TEST_TIMEOUT` | `180` | Startup timeout in seconds. |
 
 ## Troubleshooting
 
 ### "Password change required" or "Access Denied"
-
 IRIS Community Edition often enforces a password change on first login. The test infrastructure automatically handles this by:
-
 1. Creating a dedicated `test`/`test` user with `%ALL` roles.
 2. Forcefully clearing `ChangePassword` and `PasswordNeverExpires` flags via ObjectScript.
 
 If you encounter this when connecting manually:
-
 - Use the **`test`** user instead of `_SYSTEM`.
 - Or reset the `_SYSTEM` password: `Set usr = ##class(Security.Users).%OpenId("_SYSTEM"), usr.ChangePassword=0, usr.PasswordNeverExpires=1 Do usr.%Save()`
 
 ### Schema (`Graph_KG`)
-
 All tables are created in the **`Graph_KG`** schema with views mirrored into `SQLUser` for unqualified access. Use fully-qualified names in tests (`Graph_KG.nodes`) or the unqualified view aliases (`nodes`, `rdf_edges`, etc.).
 
 ### "AttributeError: module 'iris' has no attribute 'connect'"
-
 This used to happen because of a naming conflict with the `iris/` directory. That directory has been renamed to `iris_src/`, so `import iris` should now work correctly.
 
 The `iris_connection` fixture handles connection management for you.
 
 ### Resetting the Environment
-
 If the test container gets into a bad state:
-
 ```bash
 docker rm -f iris-vector-graph-main
 pytest
 ```
 
 ### Production-Scale Benchmarks
-
 The `test_nodepk_production_scale` tests create 100K nodes / 500K edges and are **skipped by default** to avoid multi-minute runtimes and segfaults under memory pressure. To run them:
-
 ```bash
 RUN_PRODUCTION_SCALE=1 pytest tests/integration/test_nodepk_production_scale.py
 ```
@@ -114,7 +105,6 @@ RUN_PRODUCTION_SCALE=1 pytest tests/integration/test_nodepk_production_scale.py
 ## Constitutional Compliance
 
 This infrastructure enforces **Principle II: Test-First with Live Database**:
-
 - ✅ All `@pytest.mark.requires_database` tests hit real IRIS.
 - ✅ No mocked database for integration tests.
 - ✅ Schema automatically initialized.

{iris_vector_graph-2.4.1 → iris_vector_graph-2.4.2}/tests/benchmarks/README.md

@@ -1,7 +1,6 @@
 # IVG Benchmark Suite (Spec 093)
 
 Repeatable benchmark harness measuring IVG traversal performance:
-
 - `ivg-os`: ObjectScript `BFSFastJson` over `^KG` globals
 - `ivg-arno`: Rust `NKGAccel.BFSJson` over `^NKG` integer adjacency (enterprise IRIS only)
 
@@ -42,11 +41,9 @@ Arno (Rust BFS via `NKGAccel.BFSJson`) requires enterprise IRIS with `libarno_ca
 deployed to the IRIS manager directory. Community IRIS reports `arno BFS not available`.
 
 To run with arno:
-
 ```bash
 IRIS_PORT=64780 conda run -n py312 python bench.py --datasets M --skip-load
 ```
-
 (assumes IVG classes and graph data already loaded in enterprise container)
 
 ## Output
@@ -57,14 +54,14 @@ JSON result files are gitignored.
 
 ## Query catalog
 
-| ID  | Pattern                          | Engine path                    |
-| --- | -------------------------------- | ------------------------------ |
-| Q1  | 1-hop count (SQL MATCH)          | IRISGraphEngine.execute_cypher |
-| Q2  | 2-hop BFS, DISTINCT nodes        | BFSFastJson / NKGAccel.BFSJson |
-| Q3  | 3-hop BFS                        | same                           |
-| Q4  | 4-hop BFS                        | same (MAXSTRING risk on M+)    |
-| Q5  | shortestPath (unweighted BFS)    | ShortestPathJson               |
-| Q6  | weighted shortestPath (Dijkstra) | ivg.shortestPath.weighted      |
+| ID | Pattern | Engine path |
+|----|---------|-------------|
+| Q1 | 1-hop count (SQL MATCH) | IRISGraphEngine.execute_cypher |
+| Q2 | 2-hop BFS, DISTINCT nodes | BFSFastJson / NKGAccel.BFSJson |
+| Q3 | 3-hop BFS | same |
+| Q4 | 4-hop BFS | same (MAXSTRING risk on M+) |
+| Q5 | shortestPath (unweighted BFS) | ShortestPathJson |
+| Q6 | weighted shortestPath (Dijkstra) | ivg.shortestPath.weighted |
 
 ## Known limitations
 

iris_vector_graph-2.4.2/tests/integration/test_driver_segfault_guard.py

@@ -0,0 +1,146 @@
+"""Subprocess-isolated guard against the intersystems-iris driver SIGSEGV
+(DP-451209 family) on the multi-JOIN parameterized SELECT shape that ivg's Cypher
+translator generates.
+
+WHY A SUBPROCESS: the failure mode is a NATIVE SIGSEGV in the driver's
+cursor.execute — it kills the Python process with NO exception and NO pytest FAIL
+(it reports as "0% coverage / process died"). A normal test cannot assert against a
+crash that erases the test process. So we run the suspect query in a CHILD process and
+assert the child did not die with signal 11 (exit code -11 / 139). If the driver
+regresses to crashing, THIS test fails visibly instead of silently killing the suite.
+
+Reference: productivity-framework/specs/058-memory-recall-bridge/IRISPYTHON_SEGFAULT_REPORT.md
+(report filed against intersystems-iris 5.3.3; ivg generates valid SQL — the driver
+crashes executing it). ivg owns the SQL generator, so it owns this regression guard.
+
+The crashing shape (translator.py): 2 LEFT JOINs to rdf_props on different "key" params
+(L3167/3180/3221) + an EXISTS structural guard (L294) + a param-concat LIKE (L2758) +
+FETCH FIRST, with multiple positional params.
+
+SCOPE / KNOWN LIMITATION: the report's crash is SCALE-DEPENDENT — it reproduced against
+~1.1M nodes / 3.1M edges, where the driver picks a particular plan. On the small fixture
+data here the same shape does NOT crash (different plan), so these tests do NOT reproduce
+the original bug. What they DO guard: that this exact query shape, through both the raw
+driver and ivg's execute_cypher, never SIGSEGVs the host on representative data — i.e.
+they catch a regression to "crashes even on small data," and they make the shape an
+explicit, runnable artifact. A faithful repro needs a large dataset; gate that behind
+IVG_SEGFAULT_SCALE_TEST=1 with a pre-loaded large graph (not run by default — too heavy).
+"""
+import os
+import sys
+import subprocess
+import textwrap
+import pytest
+
+SKIP_IRIS_TESTS = os.environ.get("SKIP_IRIS_TESTS", "false").lower() == "true"
+
+pytestmark = pytest.mark.skipif(SKIP_IRIS_TESTS, reason="SKIP_IRIS_TESTS=true")
+
+# signal 11 (SIGSEGV) shows up as returncode -11 (POSIX) or 139 (shell convention).
+SEGV_RETURNCODES = {-11, 139}
+
+
+def _conn_params(conn):
+    """Pull host/port/namespace/creds off the live test connection for the subprocess."""
+    return {
+        "hostname": getattr(conn, "hostname", "localhost"),
+        "port": int(getattr(conn, "port", os.environ.get("IVG_PORT", "21972"))),
+        "namespace": getattr(conn, "namespace", "USER"),
+        "username": getattr(conn, "username", "_SYSTEM"),
+        "password": getattr(conn, "password", "SYS"),
+    }
+
+
+def _run_in_subprocess(body: str, params: dict) -> subprocess.CompletedProcess:
+    script = textwrap.dedent(f"""
+        import faulthandler, sys
+        faulthandler.enable()
+        import iris  # the wrapper's unified iris (base dep)
+        conn = iris.dbapi.connect(
+            hostname={params['hostname']!r}, port={params['port']},
+            namespace={params['namespace']!r},
+            username={params['username']!r}, password={params['password']!r},
+        )
+        {body}
+        print("SUBPROCESS_OK")
+    """)
+    return subprocess.run(
+        [sys.executable, "-c", script],
+        capture_output=True, text=True, timeout=120,
+    )
+
+
+class TestDriverSegfaultGuard:
+    def test_raw_crash_shape_does_not_segfault(self, iris_connection):
+        """The report's minimal raw-driver repro, run in a child process. We assert the
+        child does not die with SIGSEGV. (It may raise a clean SQL error or return rows —
+        both are acceptable; a SIGSEGV is not.)"""
+        params = _conn_params(iris_connection)
+        body = textwrap.dedent('''
+            cur = conn.cursor()
+            sql = (
+                "SELECT n0.node_id AS f_id, p4.val AS f_posted_at "
+                "FROM Graph_KG.nodes n0 "
+                "JOIN Graph_KG.rdf_edges e2 ON e2.s = n0.node_id AND e2.p = ? "
+                "JOIN Graph_KG.nodes n1 ON n1.node_id = e2.o_id "
+                "LEFT JOIN Graph_KG.rdf_props p3 ON p3.s = n0.node_id AND p3.\\"key\\" = ? "
+                "LEFT JOIN Graph_KG.rdf_props p4 ON p4.s = n0.node_id AND p4.\\"key\\" = ? "
+                "WHERE EXISTS (SELECT 1 FROM Graph_KG.rdf_props _sgn0 "
+                "WHERE _sgn0.s = n0.node_id AND _sgn0.\\"key\\" = 'title') "
+                "AND ((n0.node_id LIKE (? || '%') AND p3.val = ?) AND n1.node_id = ?) "
+                "FETCH FIRST 1 ROWS ONLY"
+            )
+            params = ['IN_PROJECT', 'title', 'posted_at', 'seg:', 'x', 'seg:target']
+            try:
+                cur.execute(sql, params)
+                cur.fetchall()
+            except Exception as e:
+                # A clean exception is fine — the driver bug is the CRASH, not an error.
+                print("SUBPROCESS_SQL_EXCEPTION:", type(e).__name__)
+        ''')
+        result = _run_in_subprocess(body, params)
+        assert result.returncode not in SEGV_RETURNCODES, (
+            "intersystems-iris driver SIGSEGV on the multi-JOIN parameterized SELECT "
+            f"shape (DP-451209 family). returncode={result.returncode}\n"
+            f"stderr tail:\n{result.stderr[-800:]}"
+        )
+
+    def test_cypher_path_crash_shape_does_not_segfault(self, engine, iris_connection):
+        """The CONSUMER path: a Cypher query through execute_cypher that ivg translates
+        to the crashing shape (LIKE-prefix on id + two property projections + a related
+        node). Built on real (small) fixture data. Asserts no host SIGSEGV."""
+        # Seed a tiny graph with the property/edge shape the query touches.
+        eng = engine
+        try:
+            eng.create_node("seg:a")
+            eng.create_node("seg:target")
+            eng.set_node_property("seg:a", "title", "hello")
+            eng.set_node_property("seg:a", "posted_at", "2026-06-27")
+            eng.create_edge("seg:a", "IN_PROJECT", "seg:target")
+        except Exception:
+            pass  # best-effort seed; the point is the query shape, not the data
+
+        params = _conn_params(iris_connection)
+        body = textwrap.dedent('''
+            from iris_vector_graph.engine import IRISGraphEngine, set_schema_prefix
+            set_schema_prefix("Graph_KG")
+            eng = IRISGraphEngine(conn, embedding_dimension=384)
+            cypher = (
+                "MATCH (n)-[:IN_PROJECT]->(m) "
+                "WHERE n.node_id STARTS WITH 'seg:' AND n.title = 'hello' "
+                "AND m.node_id = 'seg:target' "
+                "RETURN n.node_id AS id, n.posted_at AS posted_at "
+                "LIMIT 1"
+            )
+            try:
+                res = eng.execute_cypher(cypher, read_only=True)
+                print("SUBPROCESS_CYPHER_ROWS:", len(getattr(res, 'rows', []) or []))
+            except Exception as e:
+                print("SUBPROCESS_CYPHER_EXCEPTION:", type(e).__name__)
+        ''')
+        result = _run_in_subprocess(body, params)
+        assert result.returncode not in SEGV_RETURNCODES, (
+            "ivg execute_cypher -> generated SQL SIGSEGV'd the host process "
+            f"(driver DP-451209 family). returncode={result.returncode}\n"
+            f"stderr tail:\n{result.stderr[-800:]}"
+        )