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

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

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

{iris_vector_graph-2.4.1 → iris_vector_graph-2.4.3}/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.3}/iris_vector_graph/_engine/query.py

@@ -355,8 +355,11 @@ class QueryMixin:
         max_hops = vl0.get("max_hops", 5)
         direction = vl0.get("direction", "out")
         def _extract_limit(s: str) -> int:
-            # IRIS SQL uses FETCH FIRST N ROWS ONLY; fall back to LIMIT N
+            # IRIS SQL uses FETCH FIRST N ROWS ONLY; the build-106 %qaqpre workaround
+            # emits SELECT TOP N instead; fall back to LIMIT N.
             m = _re.search(r"FETCH\s+FIRST\s+(\d+)\s+ROWS\s+ONLY", s, _re.IGNORECASE)
+            if not m:
+                m = _re.search(r"\bSELECT\s+(?:DISTINCT\s+)?TOP\s+(\d+)\b", s, _re.IGNORECASE)
             if not m:
                 m = _re.search(r"\bLIMIT\s+(\d+)", s, _re.IGNORECASE)
             return int(m.group(1)) if m else 0
@@ -563,8 +566,11 @@ class QueryMixin:
         import re as _re
         sql_str = sql_query.sql if isinstance(sql_query.sql, str) else (sql_query.sql[0] if sql_query.sql else "")
         if sql_query.sql:
-            # IRIS SQL uses "FETCH FIRST N ROWS ONLY" (not LIMIT N)
+            # IRIS SQL uses "FETCH FIRST N ROWS ONLY"; the build-106 %qaqpre workaround
+            # emits SELECT TOP N instead; fall back to LIMIT N.
             m = _re.search(r"FETCH\s+FIRST\s+(\d+)\s+ROWS\s+ONLY", sql_str, _re.IGNORECASE)
+            if not m:
+                m = _re.search(r"\bSELECT\s+(?:DISTINCT\s+)?TOP\s+(\d+)\b", sql_str, _re.IGNORECASE)
             if not m:
                 m = _re.search(r"\bLIMIT\s+(\d+)", sql_str, _re.IGNORECASE)
             if m:

{iris_vector_graph-2.4.1 → iris_vector_graph-2.4.3}/iris_vector_graph/cypher/translator.py

@@ -1044,9 +1044,14 @@ def _maybe_split_deep_joins(sql: str, params: list, context) -> str:
     if join_count <= JOIN_THRESHOLD:
         return sql
     import re as _re
-    select_m = _re.match(r'(SELECT\s+(?:DISTINCT\s+)?)(.*?)(\nFROM\s)', sql, _re.DOTALL)
+    # Capture an optional `TOP n` in the prefix (the FETCH-FIRST-+-JOIN workaround emits
+    # SELECT [DISTINCT] TOP n) so it stays attached to the SELECT keyword and is not
+    # swept into the column list.
+    select_m = _re.match(r'(SELECT\s+(?:DISTINCT\s+)?(?:TOP\s+\d+\s+)?)(.*?)(\nFROM\s)', sql, _re.DOTALL)
     if not select_m:
         return sql
+    # select_prefix carries any DISTINCT and TOP n; both propagate to the outer wrapper
+    # (line below), so the CTE wrap preserves the row cap from the TOP workaround.
     select_prefix = select_m.group(1)
     select_cols = select_m.group(2).strip()
     has_agg = bool(_re.search(r'\b(AVG|SUM|COUNT|MIN|MAX|STDEV|JSON_ARRAYAGG)\s*\(', select_cols))
@@ -1543,6 +1548,27 @@ def apply_pagination(
     if limit is not None or skip is not None:
         if "\nFROM " not in sql and "FROM " not in sql.split("\n")[0]:
             sql = sql.rstrip() + "\nFROM (SELECT 1) __dual"
+    # Build-106 workaround: IRIS 2026.3.0AI build 106 SIGSEGVs in %qaqpre when a
+    # multi-table JOIN is combined with `FETCH FIRST n ROWS ONLY` on VARCHAR-keyed
+    # tables (the ivg schema). `SELECT TOP n` does NOT crash. When the engine has
+    # detected the bug (engine._fetch_first_unsafe, set by a connect-time probe) and
+    # there is a LIMIT with NO SKIP (TOP cannot express OFFSET), emit TOP instead.
+    engine = getattr(context, "_engine", None)
+    fetch_first_unsafe = bool(getattr(engine, "_fetch_first_unsafe", False))
+    if (
+        limit is not None
+        and skip is None
+        and fetch_first_unsafe
+        and sql.lstrip().upper().startswith("SELECT ")
+        and " TOP " not in sql.split("\n", 1)[0].upper()
+    ):
+        # Inject `TOP n` right after the leading SELECT (and after DISTINCT if present).
+        head, sep, rest = sql.partition("SELECT ")
+        if rest[:9].upper().startswith("DISTINCT "):
+            rest = "DISTINCT " + f"TOP {limit} " + rest[9:]
+        else:
+            rest = f"TOP {limit} " + rest
+        return head + sep + rest
     if limit is not None:
         sql += f"\nFETCH FIRST {limit} ROWS ONLY"
     if skip is not None:

{iris_vector_graph-2.4.1 → iris_vector_graph-2.4.3}/iris_vector_graph/engine.py

@@ -143,6 +143,7 @@ class IRISGraphEngine(RdfExportMixin, ShaclMixin, ProvMixin, TemporalMixin, Snap
         self._rel_mapping_cache: Optional[Dict[tuple, dict]] = None
         self._connection_params: Optional[Dict[str, Any]] = None
         self._nkg_dirty: bool = False
+        self._fetch_first_unsafe_cached: Optional[bool] = None  # build-106 %qaqpre probe (lazy)
         self._native_conn = None  # dedicated connection for iris.createIRIS — never used for cursor DDL
         self._index_registry: Dict[str, str] = self._build_index_registry()
         self._pending_index_config: Dict[str, Any] = {}
@@ -209,6 +210,69 @@ class IRISGraphEngine(RdfExportMixin, ShaclMixin, ProvMixin, TemporalMixin, Snap
             )
         return cls(conn, embedding_dimension=embedding_dimension, **kwargs)
 
+    @property
+    def _fetch_first_unsafe(self) -> bool:
+        """True when this IRIS build SIGSEGVs in %qaqpre on a multi-table JOIN combined
+        with `FETCH FIRST n ROWS ONLY` (observed on irishealth 2026.3.0AI build 106).
+
+        Detected once and cached. Primary signal is a behavioral probe run in a
+        SUBPROCESS (the crash is a hard SIGSEGV — uncatchable in-process), gated on
+        having stored connection params. Falls back to a $ZVERSION build check when a
+        subprocess probe is not possible (e.g. embedded context). Defaults to safe
+        (False) if neither can determine — `TOP` is only a workaround, never required.
+        """
+        if self._fetch_first_unsafe_cached is None:
+            self._fetch_first_unsafe_cached = self._detect_fetch_first_unsafe()
+        return self._fetch_first_unsafe_cached
+
+    def _detect_fetch_first_unsafe(self) -> bool:
+        # Subprocess behavioral probe (most reliable): run the crashing shape against a
+        # VARCHAR-keyed temp table; SIGSEGV (rc -11 / 139) => unsafe.
+        if self._connection_params:
+            try:
+                import subprocess, sys, json
+                cp = json.dumps(self._connection_params)
+                script = (
+                    "import iris, json, sys\n"
+                    f"cp = json.loads(r'''{cp}''')\n"
+                    "c = iris.dbapi.connect(**cp); cur = c.cursor()\n"
+                    "for d in ['CREATE TABLE ivg_ff_probe_a (id VARCHAR(64))',"
+                    "'CREATE TABLE ivg_ff_probe_b (sid VARCHAR(64))']:\n"
+                    "    try: cur.execute(d)\n"
+                    "    except Exception: pass\n"
+                    "cur.execute('SELECT a.id FROM ivg_ff_probe_a a JOIN ivg_ff_probe_b b "
+                    "ON b.sid=a.id FETCH FIRST 1 ROWS ONLY'); cur.fetchall()\n"
+                    "print('OK')\n"
+                )
+                r = subprocess.run([sys.executable, "-c", script],
+                                   capture_output=True, text=True, timeout=60)
+                if r.returncode in (-11, 139, -6, 134):
+                    logger.warning(
+                        "IRIS build SIGSEGVs in %%qaqpre on FETCH FIRST + multi-table JOIN "
+                        "(observed on 2026.2.0AI and 2026.3.0AI AI builds); ivg will emit "
+                        "TOP for LIMIT-only queries to avoid the crash."
+                    )
+                    return True
+                return False
+            except Exception as e:
+                logger.debug("fetch-first probe failed, falling back to version check: %s", e)
+        # Fallback: $ZVERSION check (no crash risk) when a subprocess probe is not
+        # possible (e.g. embedded context with no stored connection params). The bug
+        # has been observed on the IRIS "AI" build line (2026.2.0AI build 161 and
+        # 2026.3.0AI build 106); treat AI builds as unsafe conservatively. Non-AI
+        # builds are assumed safe (FETCH FIRST retained). If a future build fixes it,
+        # this fallback can be narrowed — the subprocess probe remains authoritative.
+        try:
+            cur = self.conn.cursor()
+            cur.execute("SELECT $ZVERSION")
+            ver = str(cur.fetchone()[0])
+            import re as _re
+            if _re.search(r"20\d\d\.\d+\.\d+AI", ver):
+                return True
+        except Exception:
+            pass
+        return False
+
     def _reconnect_if_stale(self) -> None:
         try:
             cur = self.conn.cursor()

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "iris-vector-graph"
-version = "2.4.1"
+version = "2.4.3"
 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.3}/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.3}/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.3/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:]}"
+        )

iris_vector_graph-2.4.3/tests/unit/test_fetch_first_join_bug.py

@@ -0,0 +1,56 @@
+"""Translator tests for the FETCH FIRST + JOIN %qaqpre crash workaround (build-106).
+
+ROOT CAUSE (proven on a live irishealth:2026.3.0AI.106.0 container): the DB-API driver
+SIGSEGVs in %qaqpre when executing a query that combines a multi-table JOIN with
+`FETCH FIRST n ROWS ONLY` on VARCHAR-keyed tables (the ivg schema). It is NOT the
+INNER JOIN keyword (the original report's guess) — comma-join and LEFT OUTER JOIN crash
+too. `SELECT TOP n` does NOT crash and is the fix.
+
+The engine detects the bug at connect time (subprocess probe) and sets
+`engine._fetch_first_unsafe`. When set, the translator emits `SELECT TOP n` instead of a
+trailing `FETCH FIRST n ROWS ONLY` for LIMIT-only queries.
+"""
+import pytest
+from iris_vector_graph.cypher.translator import translate_to_sql
+from iris_vector_graph.cypher.parser import parse_query
+
+
+class _StubEngine:
+    """Minimal engine carrying just the bug flag the translator reads."""
+    def __init__(self, fetch_first_unsafe):
+        self._fetch_first_unsafe = fetch_first_unsafe
+    def get_table_mapping(self, label):
+        return None
+
+
+def _sql(cypher, *, unsafe, params=None):
+    ast = parse_query(cypher)
+    res = translate_to_sql(ast, params or {}, engine=_StubEngine(unsafe))
+    return res if isinstance(res, str) else str(res)
+
+
+class TestFetchFirstJoinWorkaround:
+    CYPHER = "MATCH (n)-[:R]->(m) RETURN n.node_id AS id LIMIT 5"
+
+    def test_unsafe_build_emits_top_not_fetch_first(self):
+        sql = _sql(self.CYPHER, unsafe=True)
+        assert "FETCH FIRST" not in sql, f"FETCH FIRST must not be emitted on unsafe build:\n{sql}"
+        assert "TOP 5" in sql, f"expected SELECT TOP 5:\n{sql}"
+
+    def test_safe_build_keeps_fetch_first(self):
+        sql = _sql(self.CYPHER, unsafe=False)
+        # On safe builds the existing FETCH FIRST behavior is preserved.
+        assert "FETCH FIRST 5 ROWS ONLY" in sql, f"expected FETCH FIRST on safe build:\n{sql}"
+
+    def test_unsafe_limit_only_simple_match(self):
+        sql = _sql("MATCH (n) RETURN n.node_id LIMIT 3", unsafe=True)
+        assert "FETCH FIRST" not in sql
+        assert "TOP 3" in sql
+
+    def test_unsafe_skip_plus_limit_keeps_fetch_first(self):
+        # TOP cannot express OFFSET; SKIP+LIMIT must retain FETCH FIRST + OFFSET
+        # (rare; residual build-106 risk is documented in apply_pagination).
+        sql = _sql("MATCH (n) RETURN n.node_id SKIP 2 LIMIT 4", unsafe=True)
+        assert "OFFSET 2" in sql
+        assert "FETCH FIRST 4 ROWS ONLY" in sql
+        assert "TOP 4" not in sql