fix(neo4j): namespace the CPG overlay per language (PyCFGNode, PY_* edges)

rahlk · rahlk · commit ddae36c11985 · 2026-07-02T00:16:10.000-04:00
Unprefixed CFGNode/CFG_NEXT/CDG/DDG/PARAM_IN/PARAM_OUT/SUMMARY would mingle analyzers' dependence edges in a Neo4j database holding more than one language's graph — SDK backends scope queries by label/type prefix. The vocabulary stays cross-language in shape (same suffixes, props, semantics) but is PY_-namespaced in the projection like every other row family; the JSON program_graphs section keeps the unprefixed contract since each analysis.json is its own namespace. Decision recorded in .claude/SCHEMA_DECISIONS.md. (#67)
diff --git a/.claude/SCHEMA_DECISIONS.md b/.claude/SCHEMA_DECISIONS.md
@@ -48,14 +48,24 @@ additions, all additive:
 
 ## Level-3 CPG (Neo4j) — schema.neo4j.json 1.2.0 (additive)
 
-- New label `CFGNode` (merge key `id` = `<signature>#<node_id>`; props
+- New label `PyCFGNode` (merge key `id` = `<signature>#<node_id>`; props
   `kind`, `var`, `call_node`, `start_line`, `end_line`, `_module`). Both CFG
   statements and parameter nodes ride this one label, distinguished by
   `kind` — the parity clause's label set stays minimal.
-- New edge types `HAS_CFG_NODE` (PyCallable → CFGNode), `CFG_NEXT` (prop
-  `kind`), `CDG`, `DDG` (prop `var`), `PARAM_IN`, `PARAM_OUT`, `SUMMARY` —
-  deliberately **not** `PY_`-prefixed: this vocabulary is the shared
-  cross-language CPG contract.
+- New edge types `PY_HAS_CFG_NODE` (PyCallable → PyCFGNode), `PY_CFG_NEXT`
+  (prop `kind`), `PY_CDG`, `PY_DDG` (prop `var`), `PY_PARAM_IN`,
+  `PY_PARAM_OUT`, `PY_SUMMARY`.
+- **Namespacing decision (maintainer, 2026-07-02):** the CPG vocabulary is
+  cross-language in *shape* (same suffix names, properties, semantics) but
+  **per-language-prefixed in the Neo4j projection**, like every other row
+  family (`PySymbol`, `PY_CALLS`, …). Rationale: SDK Neo4j backends scope
+  queries by label/type prefix; unprefixed `DDG`/`CFGNode` in a database
+  holding multiple languages' graphs would mingle analyzers' dependence
+  edges with no way to separate them. Each analyzer uses its language tag
+  (`TS_`/`TSCFGNode` for TypeScript, etc.). The **JSON** `program_graphs`
+  section keeps the unprefixed shared vocabulary — it lives inside each
+  analyzer's own `analysis.json`, so there is no shared namespace to
+  collide in; the SDK strips/adds the prefix at the projection boundary.
 - `CALL` SDG edges are not projected: the callable-level `PY_CALLS` twin
   already carries calls; callsite-statement granularity is recoverable via
   `PY_HAS_CALLSITE`/`PY_RESOLVES_TO`.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -20,9 +20,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Context-sensitive backward slicing** as an SDG query (`codeanalyzer.dataflow.slicing`, HRB
   two-phase traversal). Taint is deliberately left to the CLDK SDK — post-SDG it is
   language-independent labeled reachability.
-- **CPG overlay in the Neo4j projection** at level 3: `CFGNode` nodes plus the shared
-  cross-language `HAS_CFG_NODE`/`CFG_NEXT`/`CDG`/`DDG`/`PARAM_IN`/`PARAM_OUT`/`SUMMARY` edge
-  vocabulary. `schema.neo4j.json` bumped additively to **1.2.0**.
+- **CPG overlay in the Neo4j projection** at level 3: `PyCFGNode` nodes plus the
+  `PY_HAS_CFG_NODE`/`PY_CFG_NEXT`/`PY_CDG`/`PY_DDG`/`PY_PARAM_IN`/`PY_PARAM_OUT`/`PY_SUMMARY`
+  edge vocabulary — cross-language in shape, PY_-namespaced like every other row family so a
+  multi-language database never mingles analyzers' dependence edges. `schema.neo4j.json`
+  bumped additively to **1.2.0**.
 - **New flags**: `--graphs cfg,dfg,pdg,sdg` (scopes the emitted sections; strict validation —
   unknown values or use below `-a 3` exit non-zero) and `--graph-field-depth` (access-path
   k-limit, default 3 — the bound that guarantees the interprocedural fixpoint terminates).
diff --git a/README.md b/README.md
@@ -381,7 +381,9 @@ $ canpy --help
    canpy --input ./my-python-project -a 3 --graph-field-depth 2   # tighter access-path k-limit
    ```
    Level 3 also enriches the Neo4j projection (`--emit neo4j`) with the CPG overlay
-   (`:CFGNode` nodes and `CFG_NEXT`/`CDG`/`DDG`/`PARAM_IN`/`PARAM_OUT`/`SUMMARY` edges).
+   (`:PyCFGNode` nodes and `PY_CFG_NEXT`/`PY_CDG`/`PY_DDG`/`PY_PARAM_IN`/`PY_PARAM_OUT`/
+   `PY_SUMMARY` edges — the cross-language dataflow vocabulary, PY_-namespaced like every
+   other row family so multi-language databases never mingle analyzers' edges).
 
 ## Analysis levels
 
diff --git a/codeanalyzer/neo4j/project.py b/codeanalyzer/neo4j/project.py
@@ -75,7 +75,7 @@ def project(app: PyApplication, app_name: str) -> GraphRows:
         )
 
     # Level-3 CPG overlay (present only at -a 3): the same program_graphs IR
-    # projected as :CFGNode nodes and the shared cross-language edge types.
+    # projected as :PyCFGNode nodes and PY_-namespaced dependence edge types.
     if app.program_graphs is not None:
         _project_program_graphs(b, app)
 
@@ -99,16 +99,18 @@ def _signature_modules(app: PyApplication) -> dict:
 
 
 def _cfg_node_ref(b: RowBuilder, sig: str, node_id: int) -> NodeRef:
-    return NodeRef("CFGNode", "id", f"{sig}#{node_id}")
+    return NodeRef("PyCFGNode", "id", f"{sig}#{node_id}")
 
 
 def _project_program_graphs(b: RowBuilder, app: PyApplication) -> None:
-    """CFG/PDG/SDG rows: node label ``CFGNode`` (merge key ``id`` =
-    ``<signature>#<node_id>``) and edge types ``HAS_CFG_NODE`` / ``CFG_NEXT``
-    (prop ``kind``) / ``CDG`` / ``DDG`` (prop ``var``) / ``PARAM_IN`` /
-    ``PARAM_OUT`` / ``SUMMARY`` — the shared cross-language vocabulary, so no
-    ``PY_`` prefix. Parameter nodes ride the same label with their HRB kinds
-    plus ``var``/``call_node`` props (an additive, recorded extension)."""
+    """CFG/PDG/SDG rows: node label ``PyCFGNode`` (merge key ``id`` =
+    ``<signature>#<node_id>``) and edge types ``PY_HAS_CFG_NODE`` /
+    ``PY_CFG_NEXT`` (prop ``kind``) / ``PY_CDG`` / ``PY_DDG`` (prop ``var``) /
+    ``PY_PARAM_IN`` / ``PY_PARAM_OUT`` / ``PY_SUMMARY``. The vocabulary is
+    cross-language in shape but PY_-namespaced like every other row family, so
+    a multi-language database never mingles analyzers' dependence edges.
+    Parameter nodes ride the same label with their HRB kinds plus
+    ``var``/``call_node`` props (an additive, recorded extension)."""
     pg = app.program_graphs
     sig_module = _signature_modules(app)
 
@@ -117,7 +119,7 @@ def _project_program_graphs(b: RowBuilder, app: PyApplication) -> None:
         module = sig_module.get(sig)
         for n in (fg.cfg.nodes if fg.cfg else []):
             ref = b.node(
-                ["CFGNode"],
+                ["PyCFGNode"],
                 "id",
                 f"{sig}#{n.id}",
                 prune(
@@ -129,10 +131,10 @@ def _project_program_graphs(b: RowBuilder, app: PyApplication) -> None:
                     }
                 ),
             )
-            b.edge("HAS_CFG_NODE", owner, ref)
+            b.edge("PY_HAS_CFG_NODE", owner, ref)
         for p in fg.param_nodes or []:
             ref = b.node(
-                ["CFGNode"],
+                ["PyCFGNode"],
                 "id",
                 f"{sig}#{p.id}",
                 prune(
@@ -146,17 +148,17 @@ def _project_program_graphs(b: RowBuilder, app: PyApplication) -> None:
                     }
                 ),
             )
-            b.edge("HAS_CFG_NODE", owner, ref)
+            b.edge("PY_HAS_CFG_NODE", owner, ref)
         for e in (fg.cfg.edges if fg.cfg else []):
             b.edge(
-                "CFG_NEXT",
+                "PY_CFG_NEXT",
                 _cfg_node_ref(b, sig, e.source),
                 _cfg_node_ref(b, sig, e.target),
                 {"kind": e.kind},
             )
         for e in (fg.pdg.edges if fg.pdg else []):
             b.edge(
-                e.type,  # CDG | DDG
+                f"PY_{e.type}",  # PY_CDG | PY_DDG
                 _cfg_node_ref(b, sig, e.source),
                 _cfg_node_ref(b, sig, e.target),
                 prune({"var": e.var}),
@@ -166,7 +168,7 @@ def _project_program_graphs(b: RowBuilder, app: PyApplication) -> None:
         if e.type == "CALL":
             continue  # the callable-level PY_CALLS twin already carries calls
         b.edge(
-            e.type,  # PARAM_IN | PARAM_OUT | SUMMARY
+            f"PY_{e.type}",  # PY_PARAM_IN | PY_PARAM_OUT | PY_SUMMARY
             _cfg_node_ref(b, e.source.signature, e.source.node),
             _cfg_node_ref(b, e.target.signature, e.target.node),
             prune({"var": e.var}),
diff --git a/codeanalyzer/neo4j/schema.py b/codeanalyzer/neo4j/schema.py
@@ -176,13 +176,15 @@ class RelType:
             "_module": "string",
         },
     ),
-    # Level-3 CPG overlay (present only at -a 3). The label and edge types
-    # below are the shared cross-language dataflow vocabulary — deliberately
-    # NOT PY_-prefixed. `id` = "<signature>#<node_id>"; parameter-passing
-    # nodes (formal/actual in/out) ride the same label with `var`/`call_node`.
+    # Level-3 CPG overlay (present only at -a 3). The dataflow vocabulary is
+    # shared cross-language in *shape* (same suffixes, props, semantics) but
+    # namespaced per language like every other row family — a multi-language
+    # Neo4j database must never mingle one analyzer's dependence edges with
+    # another's. `id` = "<signature>#<node_id>"; parameter-passing nodes
+    # (formal/actual in/out) ride the same label with `var`/`call_node`.
     NodeLabel(
-        "CFGNode",
-        "CFGNode",
+        "PyCFGNode",
+        "PyCFGNode",
         "id",
         {
             "id": "string",
@@ -220,14 +222,15 @@ class RelType:
         {"imported_names": "string[]", "aliases": "string[]"},
     ),
     RelType("PY_DECORATED_BY", ["PyCallable"], ["PyDecorator"]),
-    # Level-3 CPG overlay (shared cross-language vocabulary, -a 3 only).
-    RelType("HAS_CFG_NODE", ["PyCallable"], ["CFGNode"]),
-    RelType("CFG_NEXT", ["CFGNode"], ["CFGNode"], {"kind": "string"}),
-    RelType("CDG", ["CFGNode"], ["CFGNode"]),
-    RelType("DDG", ["CFGNode"], ["CFGNode"], {"var": "string"}),
-    RelType("PARAM_IN", ["CFGNode"], ["CFGNode"], {"var": "string"}),
-    RelType("PARAM_OUT", ["CFGNode"], ["CFGNode"], {"var": "string"}),
-    RelType("SUMMARY", ["CFGNode"], ["CFGNode"]),
+    # Level-3 CPG overlay (-a 3 only): the cross-language dataflow vocabulary,
+    # PY_-namespaced so per-language SDK backends can scope their queries.
+    RelType("PY_HAS_CFG_NODE", ["PyCallable"], ["PyCFGNode"]),
+    RelType("PY_CFG_NEXT", ["PyCFGNode"], ["PyCFGNode"], {"kind": "string"}),
+    RelType("PY_CDG", ["PyCFGNode"], ["PyCFGNode"]),
+    RelType("PY_DDG", ["PyCFGNode"], ["PyCFGNode"], {"var": "string"}),
+    RelType("PY_PARAM_IN", ["PyCFGNode"], ["PyCFGNode"], {"var": "string"}),
+    RelType("PY_PARAM_OUT", ["PyCFGNode"], ["PyCFGNode"], {"var": "string"}),
+    RelType("PY_SUMMARY", ["PyCFGNode"], ["PyCFGNode"]),
 ]
 
 
diff --git a/schema.neo4j.json b/schema.neo4j.json
@@ -137,8 +137,8 @@
       }
     },
     {
-      "label": "CFGNode",
-      "merge_label": "CFGNode",
+      "label": "PyCFGNode",
+      "merge_label": "PyCFGNode",
       "key": "id",
       "properties": {
         "id": "string",
@@ -276,80 +276,80 @@
       "properties": {}
     },
     {
-      "type": "HAS_CFG_NODE",
+      "type": "PY_HAS_CFG_NODE",
       "from": [
         "PyCallable"
       ],
       "to": [
-        "CFGNode"
+        "PyCFGNode"
       ],
       "properties": {}
     },
     {
-      "type": "CFG_NEXT",
+      "type": "PY_CFG_NEXT",
       "from": [
-        "CFGNode"
+        "PyCFGNode"
       ],
       "to": [
-        "CFGNode"
+        "PyCFGNode"
       ],
       "properties": {
         "kind": "string"
       }
     },
     {
-      "type": "CDG",
+      "type": "PY_CDG",
       "from": [
-        "CFGNode"
+        "PyCFGNode"
       ],
       "to": [
-        "CFGNode"
+        "PyCFGNode"
       ],
       "properties": {}
     },
     {
-      "type": "DDG",
+      "type": "PY_DDG",
       "from": [
-        "CFGNode"
+        "PyCFGNode"
       ],
       "to": [
-        "CFGNode"
+        "PyCFGNode"
       ],
       "properties": {
         "var": "string"
       }
     },
     {
-      "type": "PARAM_IN",
+      "type": "PY_PARAM_IN",
       "from": [
-        "CFGNode"
+        "PyCFGNode"
       ],
       "to": [
-        "CFGNode"
+        "PyCFGNode"
       ],
       "properties": {
         "var": "string"
       }
     },
     {
-      "type": "PARAM_OUT",
+      "type": "PY_PARAM_OUT",
       "from": [
-        "CFGNode"
+        "PyCFGNode"
       ],
       "to": [
-        "CFGNode"
+        "PyCFGNode"
       ],
       "properties": {
         "var": "string"
       }
     },
     {
-      "type": "SUMMARY",
+      "type": "PY_SUMMARY",
       "from": [
-        "CFGNode"
+        "PyCFGNode"
       ],
       "to": [
-        "CFGNode"
+        "PyCFGNode"
       ],
       "properties": {}
     }
@@ -363,7 +363,7 @@
     "CREATE CONSTRAINT pycallsite_id IF NOT EXISTS FOR (x:PyCallSite) REQUIRE x.id IS UNIQUE",
     "CREATE CONSTRAINT pyattribute_id IF NOT EXISTS FOR (x:PyAttribute) REQUIRE x.id IS UNIQUE",
     "CREATE CONSTRAINT pyvariable_id IF NOT EXISTS FOR (x:PyVariable) REQUIRE x.id IS UNIQUE",
-    "CREATE CONSTRAINT cfgnode_id IF NOT EXISTS FOR (x:CFGNode) REQUIRE x.id IS UNIQUE"
+    "CREATE CONSTRAINT pycfgnode_id IF NOT EXISTS FOR (x:PyCFGNode) REQUIRE x.id IS UNIQUE"
   ],
   "indexes": [
     "CREATE INDEX py_callable_name IF NOT EXISTS FOR (c:PyCallable) ON (c.name)",
diff --git a/test/test_dataflow_cpg.py b/test/test_dataflow_cpg.py
@@ -1,9 +1,9 @@
 """Stage-8b gate: the CPG projection of the level-3 graphs.
 
-- CFGNode row count equals the JSON section's node count (CFG + parameter
+- PyCFGNode row count equals the JSON section's node count (CFG + parameter
   nodes) — the contract's count-parity assertion;
-- every CFG_NEXT/CDG/DDG/PARAM_IN/PARAM_OUT/SUMMARY edge endpoint references
-  an emitted CFGNode id (deferred-edge/no-dangling gate);
+- every PY_CFG_NEXT/PY_CDG/PY_DDG/PY_PARAM_IN/PY_PARAM_OUT/PY_SUMMARY edge
+  endpoint references an emitted PyCFGNode id (deferred-edge/no-dangling gate);
 - the Cypher snapshot renders and contains the overlay's vocabulary.
 
 Loading into a live Neo4j is exercised by the (container-gated) bolt tests;
@@ -21,7 +21,7 @@
 
 FIXTURE = Path(__file__).parent / "fixtures" / "single_functionalities" / "dataflow"
 
-CPG_EDGE_TYPES = {"CFG_NEXT", "CDG", "DDG", "PARAM_IN", "PARAM_OUT", "SUMMARY"}
+CPG_EDGE_TYPES = {"PY_CFG_NEXT", "PY_CDG", "PY_DDG", "PY_PARAM_IN", "PY_PARAM_OUT", "PY_SUMMARY"}
 
 
 @pytest.fixture(scope="module")
@@ -44,31 +44,31 @@ def test_cfg_node_count_matches_the_json_section(level3_app, rows):
         len(fg.cfg.nodes if fg.cfg else []) + len(fg.param_nodes or [])
         for fg in level3_app.program_graphs.functions.values()
     )
-    emitted = [n for n in rows.nodes if "CFGNode" in n.labels]
+    emitted = [n for n in rows.nodes if "PyCFGNode" in n.labels]
     assert expected > 0
     assert len(emitted) == expected
 
 
 def test_no_dangling_cpg_edge_endpoints(rows):
-    cfg_ids = {n.value for n in rows.nodes if "CFGNode" in n.labels}
+    cfg_ids = {n.value for n in rows.nodes if "PyCFGNode" in n.labels}
     cpg_edges = [e for e in rows.edges if e.type in CPG_EDGE_TYPES]
     assert cpg_edges, "no CPG edges projected"
     for e in cpg_edges:
-        if e.from_ref.label == "CFGNode":
+        if e.from_ref.label == "PyCFGNode":
             assert e.from_ref.value in cfg_ids, e
-        if e.to_ref.label == "CFGNode":
+        if e.to_ref.label == "PyCFGNode":
             assert e.to_ref.value in cfg_ids, e
 
 
 def test_every_callable_with_graphs_owns_its_cfg_nodes(level3_app, rows):
-    has_edges = [e for e in rows.edges if e.type == "HAS_CFG_NODE"]
+    has_edges = [e for e in rows.edges if e.type == "PY_HAS_CFG_NODE"]
     owned = {e.to_ref.value for e in has_edges}
-    cfg_ids = {n.value for n in rows.nodes if "CFGNode" in n.labels}
+    cfg_ids = {n.value for n in rows.nodes if "PyCFGNode" in n.labels}
     assert owned == cfg_ids, "every CFGNode must be owned by its callable"
 
 
 def test_cypher_snapshot_renders_the_overlay(level3_app, rows):
     cypher = render_cypher(rows, "dataflow-fixture")
-    assert ":CFGNode" in cypher
+    assert ":PyCFGNode" in cypher
     for t in CPG_EDGE_TYPES:
         assert t in cypher, f"{t} missing from the snapshot"
