Schema-v2 migration hazard: Neo4j code property must be derived from source spans, not a model field #176

Activity

1. rahlk commented on Sep 6, 2026

   

   rahlk

   on Sep 6, 2026

   CollaboratorAuthor

   More actions

   The hazard materialised in 3.0.1/3.0.2, though not as a null. code is still projected, so the fulltext index is alive — but its value changed meaning relative to v1, and the graph now disagrees with the analyzer's own JSON.

   Measured while porting the python-sdk Java Neo4j backend onto the 3.0.1 vocabulary (daytrader8, --emit neo4j, contract 2.0.0):

   • :JCallable.code in the graph is the declaration slice, beginning at the callable's span (so @Override\n public void cancelOrder().
   • JCallable.code derived from the JSON is the body block, sliced from body_span ({\n\n Connection conn = null; … \n }), which is what v1's per-callable code field held and therefore what v1's graph held too, since the projector read that field.
   • The two are related but not equal: graph_code.endswith(json_code) holds on all 1,117 callables that have a body, and they are identical on the 129 that do not.

   Two knock-on effects for consumers:

   • :JCallable carries neither body_span nor any span beyond start_line/end_line, and :JModule carries no source, so a graph-only consumer cannot recover the body block. It is not a lossy-but-derivable difference; the information is absent.
   • Anything that indexes into code by line drifts by the declaration prefix. In our parity run, code_start_line matched on 818 of 1,216 callables and tree-sitter-derived calling lines matched on 1,299 of 1,862 call-graph edges; every mismatch is a multi-line signature or an annotated declaration.

   Suggested resolution, in preference order: slice the projected code from body_span so it means what the JSON's code means, or project body_span (and ideally the module source) so a consumer can slice it themselves. Either makes the two backends agree; the current shape forces every SDK to document a divergence it cannot close.

   Unrelated to this issue but found in the same pass, in case it is useful: :JBodyNode ids end in an L:C that is a key, not a position — it equals the node's span.start column on only 629 of 4,006 call nodes, with deltas up to 12 — and the projection carries no column property, so call-site columns cannot be reconstructed from the graph at all. And LOCKS is in the contract but has zero relationships in a Maven projection, so locked_version is always null there.