Neo4j: scope destructive statements on the can:// id prefix; retire _module

[rahlk]

Spec: 2026-09-02-prune-scope-on-can-id-prefix.md · Epic: codellm-devkit/.github#50

Problem

The purge is anchored on MODULE_OWNED_PATTERN, which stops it reaching other languages, but it is application-blind: MATCH (x:{PATTERN}) WHERE x._module = $m matches a second python application sharing that module path.

Python already generates one _module index per module-owned label; those retire with the property.

What to do

• Scope the per-module purge and the orphan prune on the application's can:// id prefix (can://python/<app>), replacing the _module predicate and the label-list anchor.
• Drop _module from the projection, from the graph catalog, and from any index on it.
• Add a PyCanNode marker label to every node keyed by a can:// id, as an index anchor only — Neo4j property indexes are label-scoped, so MATCH (n) WHERE n.id STARTS WITH $p scans the whole store without one. STARTS WITH is index-backed on a range index; CONTAINS/ENDS WITH are not.
• MAJOR graph-contract bump: a property is removed.
• Grep this analyzer's SDK Neo4j backend for _module so a consumer is updated in the same train. The removal is not conditional on the answer — that was decided — but a surprise later is worse than a check now.

Two things not to get wrong

• Prefix boundary. can://python/<app> also prefixes can://python/<app>Xtra. Match descendants on prefix + '/' and the node itself by equality.
• Empty prefix. STARTS WITH '' matches every node in the database. Refuse a null or empty application id rather than falling through.

Goals

• Both destructive statements scoped by id prefix
• _module gone from projection, catalog and indexes
• Marker label added and used as the index anchor
• A test showing a second application in this same language, with a colliding module path, survives a push
• The null/empty application id case is refused
• Graph contract MAJOR bump

Definition of done

• A test that fails before and passes after
• The emitted graph is unchanged apart from _module's removal and the added marker label, shown by diffing a fixture projection
• Full test suite green

[rahlk]

A python-specific correction to the spec's §4/§6, found while fixing #171: prefix-scoping on
id will not reach two of python's node kinds, because their ids are not can:// ids at all.

:PyAttribute and :PyVariable are minted from the owner's signature, not its can:// id:

project.py:629   attr_id = f"{owner_sig}.{a.name}"        # owner_sig = cl.signature
project.py:641   var_id  = f"{owner_id}#{v.name}@{v.start_line}"

which produces service.Service.name and service.Service.announce#message@18. So
MATCH (x:PyCanNode) WHERE x.id STARTS WITH 'can://python/<app>/' matches neither, and under
this change those two node kinds would silently stop being purged at all — a regression on the
per-module purge as it stands today, which does reach them via _module.

It is also the app-blindness in §1's third row, in its worst form. Two applications don't merely
purge each other's attribute nodes — they MERGE onto the same node, because the id has no
application in it. Measured, projecting one fixture under two app names:

identical ids across two app names: 9 of 9
['service.Service.announce#message@18', 'service.Service.name', ...]

So for python this epic has a prerequisite: mint both ids from the owner's can:// id, e.g.
can://python/<app>/service.py/Service/name and
can://python/<app>/service.py/Service/announce(self,message)#message@18. That inherits the
application namespace for free and matches how PyBodyNode already builds <callable-id>@<local>.

Worth each sibling checking whether its own sub-callable nodes (java's fields/locals, typescript's)
are can://-keyed, since the same assumption is load-bearing there.

Consumer impact is nil: python-sdk reaches these nodes by traversal from the owner
(neo4j_backend.py:212,227,250) and never reads their id, and analysis.json is unaffected —
PyClassAttribute/PyVariableDeclaration have no id field, these ids exist only in the
projection.

[rahlk]

Blocked on fix/issues-171-and-172 — check after it lands

That branch already carries f15c4db "scope the Bolt purge to python-owned labels and gate it on --eager", which touches exactly the code this issue changes. It has no PR yet. Do not start this until it lands, or the two rewrite each other.

When it does land, re-read the purge before implementing: part of this issue may already be satisfied, and the rest is a different change than it looked when filed.

What will still be outstanding

f15c4db anchors on python-owned labels, which stops the purge reaching a sibling analyzer's graph. It does not make it application-scoped: MATCH (x:{MODULE_OWNED_PATTERN}) WHERE x._module = $m still matches a second python application in the same database that shares that module path. Both applications' nodes carry identical labels, so no label anchor can separate them — only the id can.

Reference implementation

codeanalyzer-java#220 is the same change, landed. The shape that worked:

• RowBuilder lifts _module off the emitted properties in one place, so no projector call site changes. It becomes an in-memory field on the node row, used only to group nodes for the incremental diff.
• The purge scopes on the module's own can:// id: the module by equality, its declarations by id STARTS WITH <id> + '/'.
• The separator is not optional. can://python/app/src/foo.py also prefixes can://python/app/src/foo.pyX. Java made it a named function with a test rather than an inlined + "/".
• A PyCanNode marker label on every can://-keyed node, indexed on id — purely so the prefix predicate can seek, since Neo4j property indexes are label-scoped. It carries no safety claim; the prefix does that.
• Python's per-label _module indexes retire with the property.

One finding from java worth checking here: the module id cannot be recovered by splitting a declaration's id, because a file key may itself contain /. Java takes it from the module's own row instead.