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 per-module purge on main is MATCH (x:CanNode {_module: $m}) ... DETACH DELETE x. Its comment — "a sibling analyzer's nodes sharing this _module key are never in scope" — is true across languages and false across applications: two TypeScript projects in one database that share a module path delete each other's nodes for it. The orphan prune and EAGER_PURGE already prefix-scope correctly; the per-module purge does not.

This analyzer covers two language namespaces, so it carries two markers.

What to do

• Scope the per-module purge and the orphan prune on the application's can:// id prefix (can://<lang>/<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 TSCanNode / JSCanNode 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://<lang>/<app> also prefixes can://<lang>/<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]

Larger than the other two — _module is also the diff key here

Flagging before anyone starts, because this analyzer uses _module for more than deletion, unlike java and python:

bolt.ts	use
:83	partition nodes by owning module
:125	MATCH (m:TSModule) RETURN m._module AS k, m.content_hash AS h — reads the property back from the database to diff which modules changed
:152, :154	the purge predicate
:179	the prune's present-set

Only the last two are deletion. Retiring the property means rewiring the content_hash diff to key on the module's can:// id instead — a database-side query, not just an in-memory rename. That is the part with no analogue in java's change.

Also still outstanding here

c1c27f3 fixed the legacy wipe that deleted other analyzers' graphs. The per-module purge on main is still application-blind:

MATCH (x:CanNode {_module: $m}) WHERE x.id IS NULL OR NOT x.id IN $keys DETACH DELETE x

Its comment — "a sibling analyzer's nodes sharing this _module key are never in scope" — is true across languages and false across applications. Two TypeScript projects in one database sharing a module path still delete each other's nodes for it. EAGER_PURGE and the orphan prune already prefix-scope correctly; this one does not.

Reference implementation

codeanalyzer-java#220, landed. Transferable parts: lift _module off the emitted properties at the single row-building choke point; scope the purge on the module id (equality for the module, id STARTS WITH <id> + '/' for its declarations); make the separator a named function with a test, because dropping it silently matches a sibling path (…/Foo.ts also prefixes …/Foo.tsX).

One decision this repo has to make that java did not

Java's marker is JCanNode. This analyzer covers two language namespaces, so per the spec it needs TSCanNode and JSCanNode, following the <lang> segment of the id each node carries — not one marker for the repo. Worth settling before the index is created, since the index is per label.

Java also dropped its legacy-schema purge entirely rather than keep a second scoping mechanism alive. If any 1.x-shaped nodes can still reach this writer, the same question applies.