python-sdk v2 model layer: one Node/Edge/Application

[rahlk]

Parent: codellm-devkit/.github#35 · Roadmap: docs/design/roadmap.md (candidate 12)

Skeleton — bodies to be filled in by the maintainer. Not started — filed ahead of pickup.
May need promotion to its own epic: this is unlikely to land in one pull request.

Problem

python-sdk models the schema four times, once per language (cldk/models/{java,python,typescript,c}). Canonical v2 exists so it can be modelled once — one Node, one Edge, one Application.

Java is the hard case, and it is not symmetric with the others. cldk/models/java/models.py is the largest model package (593 lines) and the only one carrying a shape canonical v2 explicitly forbids:

• JGraphEdges.source and .target are full JMethodDetail objects — each wrapping a nested JCallable — rather than node ids (models.py:517-523). Canonical v2's expansion rubric: "Never: … add a rich-edge variant."
• Endpoint resolution runs through a module-global mutable _CALLABLES_LOOKUP_TABLE, populated as a side effect of a pydantic field_validator and read by another (models.py:525-562). It is parse-order dependent — JApplication.validate_source must populate the table from symbol_table before any JGraphEdges validates — and fabricates a synthetic JCallable with is_implicit=True and -1 sentinels on a miss.
• JApplication exposes call_graph and system_dependency_graph as List[JGraphEdges], with no body, no cfg/ddg, and no can:// ids.

codeanalyzer-typescript's .claude/SCHEMA_DECISIONS.md names this directly: Java is the "rich-edge legacy", Python the "identity-only, the model we mirror".

Scope boundary

The model layer. Does not collapse the per-language facades (PythonAnalysis / JavaAnalysis / TypeScriptAnalysis) into one — explicitly out of scope for the parent epic. Does not change what any analyzer emits.

Goals

• TODO
• Java's rich edges replaced by identity-only edges, and _CALLABLES_LOOKUP_TABLE removed
• Blocked on: the contract spec (Canonical Neo4j projection contract: merge labels, body-node model, can:// grammar .github#36), plus any one conformant analyzer

Caveats and known risks

• The Java half is blocked on Migrate to canonical schema v2: can:// ids, statement-level CPG, identity-only edges codeanalyzer-java#179, not the reverse. JGraphEdges exists because the analyzer emits that shape; the SDK cannot move to identity-only edges while its producer emits rich ones. Java is also the only analyzer still on schema 1.1.0.
• Removing _CALLABLES_LOOKUP_TABLE is a behavioural change, not a refactor: today a miss silently fabricates a callable rather than failing, so some consumers may depend on edges that resolve to synthetic nodes.
• This work is invisible to users until the SDK's analyzer pins move off the 0.x line. pyproject.toml pins codeanalyzer-python==0.3.1 (SCHEMA_VERSION 1.2.0) and codeanalyzer-typescript==0.4.3 (SCHEMA_VERSION 1.0.0) — both schema v1. The v2 lines are unreleased development tips. Moving the pins is roadmap candidate 15 and belongs in this issue's scope or immediately after it.
• An earlier revision of this issue claimed the SDK's TypeScript Neo4j backend had drifted from its analyzer. It has not — it queries the bare Application / Module / HAS_MODULE vocabulary that v0.4.3 actually emits. That claim compared a released consumer against an unreleased producer and is withdrawn.
• TODO

Definition of done

• TODO