iris-vector-graph 4.2.0__tar.gz → 4.2.1__tar.gz

{iris_vector_graph-4.2.0 → iris_vector_graph-4.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: iris-vector-graph
-Version: 4.2.0
+Version: 4.2.1
 Summary: Native graph database layer for InterSystems IRIS — openCypher, hybrid vector search, temporal property graph, RDF export, SHACL validation
 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-4.2.0 → iris_vector_graph-4.2.1}/iris_vector_graph/_engine/class_deploy.py

@@ -134,6 +134,13 @@ class DeployResult:
     errors: List[str] = field(default_factory=list)
 
 
+def _invoke(obj, method, *args):
+    """``obj.invoke`` on a Native API object; a plain call on an ``iris.cls`` object."""
+    if hasattr(obj, "invoke"):
+        return obj.invoke(method, *args)
+    return getattr(obj, method)(*args)
+
+
 def _ok(iris_obj, status) -> bool:
     try:
         return bool(int(iris_obj.classMethodValue("%SYSTEM.Status", "IsOK", status)))
@@ -172,8 +179,8 @@ def upload_and_compile(
         text = sources[name]
         stream = iris_obj.classMethodObject("%Stream.GlobalCharacter", "%New")
         for i in range(0, len(text), STREAM_CHUNK):
-            stream.invoke("Write", text[i : i + STREAM_CHUNK])
-        stream.invoke("Rewind")
+            _invoke(stream, "Write", text[i : i + STREAM_CHUNK])
+        _invoke(stream, "Rewind")
         # Load only; compiling one class at a time would fail on forward references.
         status = iris_obj.classMethodValue("%SYSTEM.OBJ", "LoadStream", stream, "-d")
         if not _ok(iris_obj, status):
@@ -214,10 +221,16 @@ def deploy_packaged_classes(conn, force: Optional[bool] = None) -> Optional[Depl
     if force is None:
         force = os.environ.get("IVG_FORCE_CLASS_DEPLOY", "") == "1"
 
-    import iris as _iris_pkg
+    from iris_vector_graph.embedded import EmbeddedConnection, EmbeddedIRIS
+
+    if isinstance(conn, EmbeddedConnection):
+        # A process inside IRIS has no ``iris.createIRIS``.
+        iris_obj = EmbeddedIRIS()
+    else:
+        import iris as _iris_pkg
 
-    raw = conn._connection if hasattr(conn, "_connection") else conn
-    iris_obj = _iris_pkg.createIRIS(raw)
+        raw = conn._connection if hasattr(conn, "_connection") else conn
+        iris_obj = _iris_pkg.createIRIS(raw)
     namespace = str(iris_obj.classMethodValue("%SYSTEM.SYS", "NameSpace"))
 
     sources = read_class_sources(class_dir)

{iris_vector_graph-4.2.0 → iris_vector_graph-4.2.1}/iris_vector_graph/_engine/embeddings.py

@@ -415,7 +415,7 @@ class EmbeddingsMixin:
             graph_id=graph_id,
             model_key=model_key,
             table_name=table_name,
-            dimension=int(recorded_dim) if recorded_dim is not None else None,
+            dimension=int(recorded_dim) if recorded_dim not in (None, "") else None,
             dtype=(recorded_dtype or "DOUBLE"),
             index_state=index_state or None,
             index_error=index_error or None,

{iris_vector_graph-4.2.0 → iris_vector_graph-4.2.1}/iris_vector_graph/_engine/nodes_edges.py

@@ -1785,6 +1785,10 @@ class NodesEdgesMixin:
         `fk_edges_dest (graph_id, o_id)` point at `nodes (graph_id, node_id)`, so
         an edge in graph `g` whose endpoints sit in the default graph is rejected
         with `SQLCODE -121`.
+
+        Writes SQL only. It does not feed the ``^KG`` adjacency index that traversal
+        (``ShortestPathJson``, BFS, PageRank) reads, so call ``sync()`` after a batch;
+        ``create_edge`` writes both.
         """
         _ledger_check(self, "store_edge")
         graph_id = graph if graph is not None else ""

{iris_vector_graph-4.2.0 → iris_vector_graph-4.2.1}/iris_vector_graph/_engine/schema.py

@@ -898,7 +898,7 @@ class SchemaMixin:
             mechanism=mechanism or None,
             model_key=model_key or None,
             declared_config=declared_config or None,
-            dimension=int(dimension) if dimension is not None else None,
+            dimension=int(dimension) if dimension not in (None, "") else None,
             dtype=(dtype or "DOUBLE"),
         )
 
@@ -1483,7 +1483,7 @@ class SchemaMixin:
                         graph_id=graph_id,
                         model_key=model_key or None,
                         table_name=table_name,
-                        dimension=int(dimension) if dimension is not None else None,
+                        dimension=int(dimension) if dimension not in (None, "") else None,
                         dtype=dtype or None,
                         row_count=self._route_row_count(
                             cursor, table_name, graph_id, known_tables
@@ -1491,7 +1491,7 @@ class SchemaMixin:
                         index_name=index_name,
                         index_state=index_state,
                         index_error=index_error,
-                        recall_measured=float(recall) if recall is not None else None,
+                        recall_measured=float(recall) if recall not in (None, "") else None,
                         recall_measured_at=str(recall_at) if recall_at else None,
                     )
                 )
@@ -1675,7 +1675,7 @@ class SchemaMixin:
                     q_rowid=int(q_rowid),
                     node_id=str(node_id),
                     source_table=str(source_table),
-                    dimension=int(dimension) if dimension is not None else None,
+                    dimension=int(dimension) if dimension not in (None, "") else None,
                     dtype=str(dtype) if dtype else None,
                     metadata=metadata,
                     reason=str(why),
@@ -1733,7 +1733,7 @@ class SchemaMixin:
         offered = EmbeddingIdentity(
             mechanism=None,
             model_key=route.model_key,
-            dimension=int(row_dimension) if row_dimension is not None else None,
+            dimension=int(row_dimension) if row_dimension not in (None, "") else None,
             dtype=str(row_dtype or "DOUBLE"),
         )
         if route.dimension is None or int(route.dimension) != int(row_dimension or 0):

{iris_vector_graph-4.2.0 → iris_vector_graph-4.2.1}/iris_vector_graph/embedded.py

@@ -116,6 +116,22 @@ def _require_iris_sql():
         ) from exc
 
 
+def _is_no_data(exc: Exception) -> bool:
+    """SQLCODE 100: an UPDATE or DELETE that matched no row. A client cursor returns an empty
+    result for it; ``iris.sql`` raises ``SQLError`` with an empty message."""
+    return getattr(exc, "sqlcode", None) == 100 or getattr(exc.__cause__, "sqlcode", None) == 100
+
+
+def _no_data_ok(fn, *args):
+    """Call ``fn``; a no-row UPDATE/DELETE (SQLCODE 100) is not an error."""
+    try:
+        return fn(*args)
+    except Exception as exc:
+        if not _is_no_data(exc):
+            raise
+        return None
+
+
 def _is_ddtab_error(exc: Exception) -> bool:
     s = str(exc)
     return "<UNIMPLEMENTED>" in s or "ddtab" in s
@@ -221,39 +237,30 @@ class EmbeddedCursor:
             return self._iris_sql
         return _require_iris_sql()
 
-    def execute(self, sql, params=None):
-        iris_sql = self._get_iris_sql()
-        lowered = sql.strip().upper()
-        if lowered in ("START TRANSACTION", "COMMIT", "ROLLBACK",
-                       "BEGIN", "BEGIN TRANSACTION"):
-            self._rs = None
-            self._rows = None
-            self.description = None
-            self.rowcount = -1
-            return
-
+    def _run(self, iris_sql, sql, params):
+        """Run ``sql`` by the first embedded path that accepts it; return the result set."""
         try:
             if params and any(isinstance(p, str) and p == "" for p in params):
                 # An empty string bound as a parameter reaches the engine as SQL NULL, so a
                 # NOT NULL column holding '' (graph_id of the default graph) rejected every
                 # default-graph write. Inline the literals for these statements.
-                self._rs = _exec_inline(iris_sql, sql, params)
+                return _exec_inline(iris_sql, sql, params)
             else:
                 stmt = iris_sql.prepare(sql)
                 if params:
-                    self._rs = stmt.execute(*params)
+                    return stmt.execute(*params)
                 else:
-                    self._rs = stmt.execute()
+                    return stmt.execute()
         except Exception as exc1:
             if not _is_ddtab_error(exc1):
                 raise
             try:
-                self._rs = iris_sql.exec(_inline_params(sql, params or []))
+                return iris_sql.exec(_inline_params(sql, params or []))
             except Exception as exc2:
                 if not _is_ddtab_error(exc2):
                     raise
                 try:
-                    self._rs = _sql_statement_execute(sql, params)
+                    return _sql_statement_execute(sql, params)
                 except Exception as exc3:
                     raise RuntimeError(
                         f"All three embedded SQL paths failed.\n"
@@ -262,12 +269,35 @@ class EmbeddedCursor:
                         f"  %%SQL.Statement: {exc3}"
                     ) from exc3
 
+
+    def execute(self, sql, params=None):
+        iris_sql = self._get_iris_sql()
+        lowered = sql.strip().upper()
+        if lowered in ("START TRANSACTION", "COMMIT", "ROLLBACK",
+                       "BEGIN", "BEGIN TRANSACTION"):
+            self._rs = None
+            self._rows = None
+            self.description = None
+            self.rowcount = -1
+            return
+
+        no_data = False
+        try:
+            self._rs = self._run(iris_sql, sql, params)
+        except Exception as exc:
+            if not _is_no_data(exc):
+                raise
+            self._rs = None
+            no_data = True
+        if self._rs is None and lowered.startswith(("UPDATE", "DELETE", "INSERT")):
+            no_data = True  # _exec_inline already folded SQLCODE 100 into "no result"
+
         self._rows = None
         self._pos = 0
 
         # Populate description from result set metadata if available
         self.description = None
-        self.rowcount = -1
+        self.rowcount = 0 if no_data else -1
         if self._rs is not None:
             try:
                 cols = self._rs.columnCount()
@@ -289,9 +319,9 @@ class EmbeddedCursor:
             for params in seq:
                 if any(isinstance(p, str) and p == "" for p in params):
                     # same reason as execute(): a bound '' arrives as NULL
-                    _exec_inline(iris_sql, sql, params)
+                    _no_data_ok(_exec_inline, iris_sql, sql, params)
                 else:
-                    stmt.execute(*params)
+                    _no_data_ok(stmt.execute, *params)
                 count += 1
         except Exception as exc:
             if not _is_ddtab_error(exc):
@@ -299,11 +329,11 @@ class EmbeddedCursor:
             count = 0
             for params in seq:
                 try:
-                    iris_sql.exec(_inline_params(sql, list(params)))
+                    _no_data_ok(iris_sql.exec, _inline_params(sql, list(params)))
                 except Exception as exc2:
                     if not _is_ddtab_error(exc2):
                         raise
-                    _sql_statement_execute(sql, list(params))
+                    _no_data_ok(_sql_statement_execute, sql, list(params))
                 count += 1
         self.rowcount = count
         self._rs = None
@@ -350,6 +380,11 @@ class EmbeddedCursor:
         self._rows = None
 
 
+def _py_name(method):
+    """Embedded Python spells a ``%`` system method with a leading underscore (``%New`` is ``_New``)."""
+    return "_" + method[1:] if method.startswith("%") else method
+
+
 class EmbeddedIRIS:
     """The slice of the Native API (``iris.createIRIS``) that class-method callers use, for a
     process running inside IRIS, where ``createIRIS`` is not available.
@@ -369,13 +404,47 @@ class EmbeddedIRIS:
         return iris.cls(name)
 
     def classMethodValue(self, cls, method, *args):
-        return getattr(self._cls(cls), method)(*args)
+        return getattr(self._cls(cls), _py_name(method))(*args)
 
     def classMethodVoid(self, cls, method, *args):
-        getattr(self._cls(cls), method)(*args)
+        getattr(self._cls(cls), _py_name(method))(*args)
 
     def classMethodObject(self, cls, method, *args):
-        return getattr(self._cls(cls), method)(*args)
+        return getattr(self._cls(cls), _py_name(method))(*args)
+
+    def get(self, name, *subscripts):
+        """A global node, ``None`` when undefined: ``get("^IVG.Deploy", "fingerprint")``."""
+        return self._gref(name)[self._key(subscripts)]
+
+    def set(self, value, name, *subscripts):
+        self._gref(name)[self._key(subscripts)] = value
+
+    def getString(self, name, *subscripts):
+        """The node's value as text, ``None`` when undefined (the Native API's ``getString``)."""
+        value = self.get(name, *subscripts)
+        return None if value is None else str(value)
+
+    def kill(self, name, *subscripts):
+        """Kill the node and everything below it."""
+        self._gref(name).kill(list(subscripts))
+
+    def isDefined(self, name, *subscripts):
+        """0 undefined, 1 value, 10 children only, 11 both (``$Data``)."""
+        return int(self._gref(name).data(list(subscripts)))
+
+    def nextSubscript(self, reverse, name, *subscripts):
+        """The sibling after the last subscript (before it when ``reverse``); ``None`` at the end."""
+        return self._gref(name).order(list(subscripts), -1 if reverse else 1)
+
+    def _gref(self, name):
+        iris = self._iris
+        if iris is None:
+            import iris as iris  # noqa: PLC0415 - only importable inside IRIS
+        return iris.gref(name)
+
+    @staticmethod
+    def _key(subscripts):
+        return subscripts[0] if len(subscripts) == 1 else tuple(subscripts)
 
 
 class EmbeddedConnection:

{iris_vector_graph-4.2.0 → iris_vector_graph-4.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "iris-vector-graph"
-version = "4.2.0"
+version = "4.2.1"
 description = "Native graph database layer for InterSystems IRIS — openCypher, hybrid vector search, temporal property graph, RDF export, SHACL validation"
 readme = "README.md"
 license = "MIT"

iris_vector_graph-4.2.1/tests/e2e/test_embedded_irispython_e2e.py

@@ -0,0 +1,199 @@
+"""A fresh namespace, driven from a process inside IRIS (irispython), end to end.
+
+Unit tests with a fake ``iris`` module missed three 4.2.0 defects that only a real irispython
+process shows (Mindwalk reports, 2026-10-10): ``deploy_packaged_classes`` called the absent
+``iris.createIRIS``; ``iris.cls(...).%New`` is ``_New`` there; an adopted registry row's NULL width
+comes back as ``''``. This runs the wheel's code the way Mindwalk does, in a namespace made for the
+run, and asserts database state afterwards.
+
+The repo checkout is copied into the container and run by the container's own ``irispython``; no
+port is dialled, so which instance a port reaches does not matter.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import uuid
+from pathlib import Path
+
+import pytest
+
+CONTAINER = os.environ.get("IVG_TEST_CONTAINER", "ivg-iris-enterprise")
+ROOT = Path(__file__).resolve().parents[2]
+IRISPYTHON = "/usr/irissys/bin/irispython"
+
+pytestmark = pytest.mark.e2e
+
+
+def _docker(*args, input=None, timeout=900, user=None):
+    cmd = ["docker", *args]
+    return subprocess.run(cmd, input=input, capture_output=True, text=True, timeout=timeout)
+
+
+def _session(namespace, script):
+    return _docker("exec", "-i", CONTAINER, "iris", "session", "IRIS", "-U", namespace, input=script, timeout=300).stdout
+
+
+@pytest.fixture(scope="module")
+def namespace():
+    try:
+        _docker("inspect", CONTAINER, timeout=30).check_returncode()
+    except (OSError, subprocess.SubprocessError):
+        pytest.skip(f"container {CONTAINER} not available")
+    ns = "IVGEMB" + uuid.uuid4().hex[:6].upper()
+    directory = f"/usr/irissys/mgr/{ns.lower()}/"
+    created = _session(
+        "%SYS",
+        f'Set dir="{directory}"\nDo ##class(%File).CreateDirectoryChain(dir)\n'
+        "Set db=##class(SYS.Database).%New()  Set db.Directory=dir  Set sc=db.%Save()\n"
+        f'Kill p  Set p("Directory")=dir  Set sc=##class(Config.Databases).Create("{ns}",.p)\n'
+        f'Kill p  Set p("Globals")="{ns}",p("Routines")="{ns}"\n'
+        f'Set sc=##class(Config.Namespaces).Create("{ns}",.p)\n'
+        f'Write "NS=",##class(Config.Namespaces).Exists("{ns}"),!\nHalt\n',
+    )
+    if "NS=1" not in created:
+        pytest.skip(f"could not create {ns}: {created[-300:]}")
+    yield ns
+    # Order matters: removing the directory of a database that is still mounted, or still in the
+    # configuration, leaves an instance that cannot start (its WIJ recovery opens IRIS.DAT).
+    _session(
+        "%SYS",
+        f'Set sc=##class(Config.Namespaces).Delete("{ns}")\n'
+        f'Set sc=##class(SYS.Database).DismountDatabase("{directory}")\n'
+        f'Set sc=##class(Config.Databases).Delete("{ns}")\n'
+        f'Write "LEFT=",##class(Config.Databases).Exists("{ns}"),!\n'
+        f'If \'##class(Config.Databases).Exists("{ns}") {{ Do ##class(%File).RemoveDirectoryTree("{directory}") }}\nHalt\n',
+    )
+
+
+@pytest.fixture(scope="module")
+def source_in_container():
+    dest = f"/tmp/ivg_emb_{uuid.uuid4().hex[:8]}"
+    _docker("exec", "-u", "root", CONTAINER, "mkdir", "-p", f"{dest}/iris_src").check_returncode()
+    for src, to in ((ROOT / "iris_vector_graph", f"{dest}/iris_vector_graph"), (ROOT / "iris_src" / "src", f"{dest}/iris_src/src")):
+        _docker("cp", str(src), f"{CONTAINER}:{to}").check_returncode()
+    _docker("exec", "-u", "root", CONTAINER, "chmod", "-R", "a+rX", dest)
+    yield dest
+    _docker("exec", "-u", "root", CONTAINER, "rm", "-r", "-f", dest)
+
+
+SCRIPT = r'''
+import json, logging, sys
+sys.path.insert(0, "{src}")
+import iris
+iris.cls("%SYSTEM.Process").SetNamespace("{ns}")
+records = []
+class H(logging.Handler):
+    def emit(self, r): records.append(r.getMessage())
+logging.getLogger().addHandler(H()); logging.getLogger().setLevel(logging.WARNING)
+from iris_vector_graph.engine import IRISGraphEngine
+from iris_vector_graph.embedded import EmbeddedConnection
+out = {{}}
+e = IRISGraphEngine(EmbeddedConnection(), embedding_dimension=4)
+out["init"] = e.initialize_schema()
+out["deploy_warnings"] = [m for m in records if "deploy" in m.lower() and "fail" in m.lower()]
+out["pagerank_class"] = bool(int(iris.cls("%Dictionary.CompiledClass")._ExistsId("Graph.KG.PageRank")))
+e.create_node("emb:a", labels=["T"])
+out["store"] = e.store_embedding("emb:a", [0.1, 0.2, 0.3, 0.4])
+cur = e.conn.cursor()
+cur.execute("SELECT COUNT(*) FROM Graph_KG.kg_NodeEmbeddings WHERE node_id = 'emb:a'")
+out["rows"] = list(cur.fetchone())[0]
+inv = e.embedding_inventory()
+out["inventory"] = len(inv)
+e.create_node("emb:b")
+e.create_edge("emb:a", "R", "emb:b")
+e.sync()
+out["edges"] = e.get_edge_count() if hasattr(e, "get_edge_count") else None
+out["deleted"] = e.delete_node("emb:a")
+out["gone"] = e.get_node("emb:a") is None
+e.store_node("TMP:1", labels=["Tmp"], properties={{"k": "v"}})
+e.store_node("TMP:2")
+e.store_edge("TMP:1", "R", "TMP:2")
+e.store_embedding("TMP:1", [0.4, 0.3, 0.2, 0.1])
+out["deleted_legacy_written"] = e.delete_node("TMP:1")
+out["legacy_gone"] = e.get_node("TMP:1") is None
+out["delete_missing"] = e.delete_node("TMP:nope")
+cur2 = e.conn.cursor()
+for verb, sql, args in (
+    ("update", "UPDATE Graph_KG.rdf_labels SET label = ? WHERE s = ?", ["x", "no-such-node"]),
+    ("update_inline", "UPDATE Graph_KG.rdf_labels SET label = ? WHERE s = ?", ["", "no-such-node"]),
+    ("delete", "DELETE FROM Graph_KG.rdf_labels WHERE s = ?", ["no-such-node"]),
+):
+    try:
+        cur2.execute(sql, args)
+        out["nodata_" + verb] = [cur2.rowcount, cur2.fetchall()]
+    except Exception as exc:
+        out["nodata_" + verb] = "RAISED " + repr(exc)
+from iris_vector_graph.embedded import EmbeddedIRIS
+n = EmbeddedIRIS()
+n.set("1", "^IVGEmbProbe", "a", "x"); n.set("2", "^IVGEmbProbe", "b")
+seen, cur = [], n.nextSubscript(False, "^IVGEmbProbe", "")
+while cur is not None:
+    seen.append(cur); cur = n.nextSubscript(False, "^IVGEmbProbe", cur)
+out["native_order"] = seen
+out["native_string"] = n.getString("^IVGEmbProbe", "b")
+out["native_defined"] = [n.isDefined("^IVGEmbProbe", "a"), n.isDefined("^IVGEmbProbe", "b"), n.isDefined("^IVGEmbProbe", "zz")]
+n.kill("^IVGEmbProbe", "a")
+out["native_after_kill"] = [n.isDefined("^IVGEmbProbe", "a"), n.getString("^IVGEmbProbe", "a")]
+n.kill("^IVGEmbProbe")
+print("RESULT=" + json.dumps(out, default=str))
+'''
+
+
+@pytest.fixture(scope="module")
+def run(namespace, source_in_container):
+    script = SCRIPT.format(src=source_in_container, ns=namespace)
+    path = f"{source_in_container}/probe.py"
+    local = ROOT / "tests" / "e2e" / ".probe_tmp.py"
+    local.write_text(script)
+    try:
+        _docker("cp", str(local), f"{CONTAINER}:{path}").check_returncode()
+    finally:
+        local.unlink(missing_ok=True)
+    done = _docker("exec", CONTAINER, "sh", "-c", f"cd /tmp && {IRISPYTHON} {path}", timeout=900)
+    lines = [ln for ln in done.stdout.splitlines() if ln.startswith("RESULT=")]
+    assert lines, f"no result from irispython.\nstdout: {done.stdout[-1500:]}\nstderr: {done.stderr[-1500:]}"
+    return json.loads(lines[-1][len("RESULT="):])
+
+
+def test_initialize_schema_deploys_the_packaged_classes_from_inside_iris(run):
+    assert run["deploy_warnings"] == []
+    assert run["pagerank_class"] is True
+    assert run["init"].get("objectscript_deployed") is True
+
+
+def test_the_first_store_embedding_after_a_fresh_schema_stores_the_vector(run):
+    assert run["store"] is True
+    assert run["rows"] == 1
+
+
+def test_the_embedding_inventory_reads_adopted_routes(run):
+    assert run["inventory"] >= 1
+
+
+def test_delete_node_reports_that_it_deleted(run):
+    assert run["gone"] is True
+    assert run["deleted"] is True
+
+
+def test_delete_node_on_a_node_written_with_the_legacy_writers_reports_that_it_deleted(run):
+    assert run["legacy_gone"] is True
+    assert run["deleted_legacy_written"] is True
+
+
+def test_delete_node_of_a_node_that_does_not_exist_reports_false(run):
+    assert run["delete_missing"] is False
+
+
+@pytest.mark.parametrize("verb", ["update", "update_inline", "delete"])
+def test_a_statement_that_matches_no_row_is_an_empty_result_not_an_error(run, verb):
+    assert run["nodata_" + verb] == [0, []]
+
+
+def test_the_native_subset_that_migrations_use_works_on_real_globals(run):
+    assert run["native_order"] == ["a", "b"]
+    assert run["native_string"] == "2"
+    assert run["native_defined"] == [10, 1, 0]
+    assert run["native_after_kill"] == [0, None]

iris_vector_graph-4.2.1/tests/unit/test_embedded_class_deploy.py

@@ -0,0 +1,153 @@
+"""deploy_packaged_classes inside IRIS (irispython), where ``iris.createIRIS`` does not exist.
+
+Reported by Mindwalk against 4.2.0: ``initialize_schema()`` on an ``EmbeddedConnection`` logged
+"Packaged ObjectScript deploy failed: Cannot call an iris.package wrapper ... createIRIS" and
+deployed nothing. The fake ``iris`` module below has ``cls`` and ``gref`` (what a process inside
+IRIS has) and no ``createIRIS``.
+"""
+
+from __future__ import annotations
+
+import sys
+import types
+
+import pytest
+
+from iris_vector_graph._engine import class_deploy as cd
+from iris_vector_graph.embedded import EmbeddedConnection
+
+
+class FakeStream:
+    def __init__(self):
+        self.text = ""
+
+    def Write(self, chunk):
+        self.text += chunk
+
+    def Rewind(self):
+        pass
+
+
+class FakeServer:
+    """The ObjectScript side: classes loaded, compiled, and the global the marker lives in."""
+
+    def __init__(self, existing=()):
+        self.loaded = {}
+        self.compiled = []
+        self.existing = set(existing)
+        self.globals = {}
+
+    def cls(self, name):
+        server = self
+
+        class Cls:
+            def __getattr__(self_inner, method):
+                def call(*args):
+                    return server.call(name, method, args)
+
+                return call
+
+        return Cls()
+
+    def call(self, cls, method, args):
+        method = "%" + method[1:] if method.startswith("_") else method  # as irispython spells it
+        if (cls, method) == ("%SYSTEM.SYS", "NameSpace"):
+            return "MINDWALK"
+        if (cls, method) == ("%SYS.Python", "Import"):
+            return object()
+        if (cls, method) == ("%Dictionary.CompiledClass", "%ExistsId"):
+            return 1 if args[0] in self.existing else 0
+        if (cls, method) == ("%Stream.GlobalCharacter", "%New"):
+            return FakeStream()
+        if (cls, method) == ("%SYSTEM.OBJ", "LoadStream"):
+            stream = args[0]
+            assert isinstance(stream, FakeStream), "the stream must reach ObjectScript unwrapped"
+            first = stream.text.splitlines()[0]
+            self.loaded[first.split()[1]] = stream.text
+            return 1
+        if (cls, method) == ("%SYSTEM.OBJ", "CompileList"):
+            self.compiled.append(args[0])
+            return 1
+        if (cls, method) == ("%SYSTEM.Status", "IsOK"):
+            return 1
+        raise AssertionError(f"unexpected call {cls}.{method}{args}")
+
+    def gref(self, name):
+        store = self.globals
+
+        class Ref:
+            def __getitem__(self, subs):
+                return store.get((name, subs))
+
+            def __setitem__(self, subs, value):
+                store[(name, subs)] = value
+
+        return Ref()
+
+
+@pytest.fixture
+def server(monkeypatch, tmp_path):
+    srv = FakeServer(existing={cd.SENTINEL_CLASS})
+    fake = types.ModuleType("iris")
+    fake.cls = srv.cls
+    fake.gref = srv.gref  # no createIRIS: a process inside IRIS does not have one
+    monkeypatch.setitem(sys.modules, "iris", fake)
+    classes = tmp_path / "Graph" / "KG"
+    classes.mkdir(parents=True)
+    (classes / "Alpha.cls").write_text("Class Graph.KG.Alpha Extends %RegisteredObject\n{\n}\n")
+    monkeypatch.setattr(cd, "packaged_class_dir", lambda: tmp_path)
+    return srv
+
+
+def test_deploys_the_packaged_classes_without_createiris(server):
+    result = cd.deploy_packaged_classes(EmbeddedConnection())
+    assert result.errors == []
+    assert result.deployed and not result.unchanged
+    assert list(server.loaded) == ["Graph.KG.Alpha"]
+    assert server.compiled[0] == "Graph.KG.Alpha.cls"
+
+
+def test_the_second_deploy_is_a_no_op_once_the_marker_is_written(server):
+    cd.deploy_packaged_classes(EmbeddedConnection())
+    assert server.globals[("^IVG.Deploy", "fingerprint")], "the marker was not written"
+    loaded = dict(server.loaded)
+    again = cd.deploy_packaged_classes(EmbeddedConnection())
+    assert again.unchanged and server.loaded == loaded
+
+
+def test_percent_methods_are_spelled_with_an_underscore_inside_iris():
+    """Measured under irispython: ``iris.cls(...).%New`` is ``SystemError``, ``_New`` works."""
+    from iris_vector_graph.embedded import EmbeddedIRIS
+
+    seen = []
+
+    class Cls:
+        def __getattr__(self, name):
+            seen.append(name)
+            return lambda *a: 1
+
+    fake = types.SimpleNamespace(cls=lambda n: Cls())
+    e = EmbeddedIRIS(fake)
+    e.classMethodValue("%Dictionary.CompiledClass", "%ExistsId", "X")
+    e.classMethodObject("%Stream.GlobalCharacter", "%New")
+    e.classMethodVoid("A.B", "Plain")
+    assert seen == ["_ExistsId", "_New", "Plain"]
+
+
+def test_embedded_iris_reads_and_writes_a_global_node():
+    from iris_vector_graph.embedded import EmbeddedIRIS
+
+    store = {}
+
+    class Ref:
+        def __getitem__(self, k):
+            return store.get(k)
+
+        def __setitem__(self, k, v):
+            store[k] = v
+
+    e = EmbeddedIRIS(types.SimpleNamespace(gref=lambda name: Ref()))
+    assert e.get("^G", "a") is None
+    e.set("v", "^G", "a")
+    e.set("w", "^G", "a", "b")
+    assert (e.get("^G", "a"), e.get("^G", "a", "b")) == ("v", "w")