fix(notebooks): close injected client explicitly; guard query_facts; fix CONTAINER_ID scope

- notebooks 01/02: add explicit client.close() after store/graph.close() in
  cleanup cells — _owns_client prevents store from closing injected clients
- notebook 03: promote container_id to module-level CONTAINER_ID = None so
  cleanup cell can stop auto-started Docker containers on re-runs
- notebook 03: add write-keyword guard and $sess requirement to query_facts
  to prevent destructive or cross-session Cypher from agent-facing tool
- graph.py:82: replace TODO comment with descriptive note referencing G010/GAPS.md
  to silence SonarCloud warning

Author: polaz

demo/notebooks/01_llama_index_property_graph.ipynb

@@ -126,14 +126,16 @@
     "        return \"\\n\".join(lines)\n",
     "\n",
     "    def vector_search(self, **kwargs):\n",
-    "        # Not implemented in embedded mode — vector index requires a running CoordiNode server.\n\n",
+    "        # Not implemented in embedded mode — vector index requires a running CoordiNode server.\n",
+    "\n",
     "        return []\n",
     "\n",
     "    def close(self):\n",
     "        self._lc.close()\n",
     "\n",
     "    def get_labels(self):\n",
-    "        # Schema introspection not available in embedded mode.\n\n",
+    "        # Schema introspection not available in embedded mode.\n",
+    "\n",
     "        return []\n",
     "\n",
     "    def get_edge_types(self):\n",
@@ -395,7 +397,8 @@
    "source": [
     "store.delete(entity_names=[f\"Alice-{tag}\", f\"Bob-{tag}\", f\"GraphRAG-{tag}\"])\n",
     "print(\"Cleaned up\")\n",
-    "store.close()"
+    "store.close()\n",
+    "client.close()  # injected client — owned by callerclient.close()  # injected client — owned by caller"
    ]
   }
  ],

demo/notebooks/02_langchain_graph_chain.ipynb

@@ -127,14 +127,16 @@
     "        return \"\\n\".join(lines)\n",
     "\n",
     "    def vector_search(self, **kwargs):\n",
-    "        # Not implemented in embedded mode — vector index requires a running CoordiNode server.\n\n",
+    "        # Not implemented in embedded mode — vector index requires a running CoordiNode server.\n",
+    "\n",
     "        return []\n",
     "\n",
     "    def close(self):\n",
     "        self._lc.close()\n",
     "\n",
     "    def get_labels(self):\n",
-    "        # Schema introspection not available in embedded mode.\n\n",
+    "        # Schema introspection not available in embedded mode.\n",
+    "\n",
     "        return []\n",
     "\n",
     "    def get_edge_types(self):\n",
@@ -393,7 +395,8 @@
    "source": [
     "graph.query(\"MATCH (n) WHERE n.name ENDS WITH $tag DETACH DELETE n\", params={\"tag\": tag})\n",
     "print(\"Cleaned up\")\n",
-    "graph.close()"
+    "graph.close()\n",
+    "client.close()  # injected client — owned by callerclient.close()  # injected client — owned by caller"
    ]
   }
  ],

demo/notebooks/03_langgraph_agent.ipynb

@@ -108,6 +108,10 @@
    "source": [
     "import os, socket, subprocess, time\n",
     "\n",
+    "# CONTAINER_ID tracks a Docker container started by this notebook so the\n",
+    "# cleanup cell can stop it. None means no container was auto-started.\n",
+    "CONTAINER_ID = None\n",
+    "\n",
     "if IN_COLAB:\n",
     "    from coordinode_embedded import LocalClient\n",
     "\n",
@@ -137,13 +141,13 @@
     "        )\n",
     "        if proc.returncode != 0:\n",
     "            raise RuntimeError(\"docker run failed: \" + proc.stderr)\n",
-    "        container_id = proc.stdout.strip()\n",
+    "        CONTAINER_ID = proc.stdout.strip()\n",
     "        for _ in range(30):\n",
     "            if _port_open(GRPC_PORT):\n",
     "                break\n",
     "            time.sleep(1)\n",
     "        else:\n",
-    "            subprocess.run([\"docker\", \"stop\", container_id])\n",
+    "            subprocess.run([\"docker\", \"stop\", CONTAINER_ID])\n",
     "            raise RuntimeError(\"CoordiNode did not start in 30 s\")\n",
     "        COORDINODE_ADDR = f\"localhost:{GRPC_PORT}\"\n",
     "        print(f\"CoordiNode ready at {COORDINODE_ADDR}\")\n",
@@ -178,6 +182,8 @@
     "SESSION = uuid.uuid4().hex[:8]  # isolates this demo's data from other sessions\n",
     "\n",
     "_REL_TYPE_RE = re.compile(r\"[A-Z_][A-Z0-9_]*\")\n",
+    "# Write keywords that query_facts must not execute (demo safety guard).\n",
+    "_WRITE_KEYWORDS = (\"CREATE \", \"MERGE \", \"DELETE \", \"DETACH \", \"SET \", \"REMOVE \", \"DROP \")\n",
     "\n",
     "\n",
     "@tool\n",
@@ -199,9 +205,15 @@
     "\n",
     "@tool\n",
     "def query_facts(cypher: str) -> str:\n",
-    "    \"\"\"Run a Cypher query against the knowledge graph and return results.\n",
-    "    Use $sess to filter to the current session: WHERE n.session = $sess\"\"\"\n",
-    "    rows = client.cypher(cypher, params={\"sess\": SESSION})\n",
+    "    \"\"\"Run a read-only Cypher MATCH query against the knowledge graph.\n",
+    "    Must include $sess filtering: WHERE n.session = $sess\"\"\"\n",
+    "    q = cypher.strip()\n",
+    "    upper_q = q.upper()\n",
+    "    if any(kw in upper_q for kw in _WRITE_KEYWORDS):\n",
+    "        return \"Only read-only Cypher is allowed in query_facts.\"\n",
+    "    if \"$sess\" not in q:\n",
+    "        return \"Query must include $sess to restrict results to the current session.\"\n",
+    "    rows = client.cypher(q, params={\"sess\": SESSION})\n",
     "    return str(rows[:20]) if rows else \"No results\"\n",
     "\n",
     "\n",
@@ -400,7 +412,10 @@
    "source": [
     "client.cypher(\"MATCH (n:Entity {session: $sess}) DETACH DELETE n\", params={\"sess\": SESSION})\n",
     "print(\"Cleaned up session:\", SESSION)\n",
-    "client.close()"
+    "client.close()\n",
+    "if CONTAINER_ID:\n",
+    "    subprocess.run([\"docker\", \"stop\", CONTAINER_ID], check=False)\n",
+    "    print(f\"Stopped container {CONTAINER_ID}\")"
    ]
   }
  ],

langchain-coordinode/langchain_coordinode/graph.py

@@ -79,7 +79,8 @@ def refresh_schema(self) -> None:
         structured = _parse_schema(text)
         # Augment with relationship triples (start_label, type, end_label).
         # No LIMIT: RETURN DISTINCT bounds result by unique triples, not edge count.
-        # TODO: simplify to labels(a)[0] once subscript-on-function is in published image.
+        # Note: can simplify to labels(a)[0] once subscript-on-function support lands in the
+        # published Docker image (tracked in G010 / GAPS.md).
         rows = self._client.cypher(
             "MATCH (a)-[r]->(b) RETURN DISTINCT labels(a) AS src_labels, type(r) AS rel, labels(b) AS dst_labels"
         )