Backwards-compatibility policy for the v2 model layer #308

Parent: codellm-devkit/.github#35 · Spec: docs/design/specs/2026-09-03-python-sdk-canonical-v2.md (#318) § 6

Problem

python-sdk carries four per-language model packages plus per-language facades. Canonical v2's premise is one Node / Edge / Application. "Strong backwards compatibility" had to be defined before the new model layer was designed, or the policy becomes whatever the implementation made convenient.

Decision

2.0.0 — a major bump, API-stable via a view layer. The v2 models replace the v1 ones outright. There is no parallel v1 model layer and no deprecation window.

Preserved

• Every public accessor's name, signature and return type on all four facades (PythonAnalysis, JavaAnalysis, TypeScriptAnalysis, CAnalysis).
• The public model class names (PyCallable, JCallable, TSCallable, …) — now subclasses of the shared bases in cldk/models/cpg/.

Accessors whose v1 return type no longer exists as stored data become computed views over the spine: get_method_body(sig) slices module.source[callable.span.bytes]; get_call_sites(...) reads body{} entries with kind == "call"; get_system_dependency_graph() returns the v2 SDG over identity-only edges.

Not preserved — consumers reaching past the public API:

• NetworkX node-key types (now can:// ids).
• JGraphEdges rich endpoints (source / target as JMethodDetail objects).
• _CALLABLES_LOOKUP_TABLE and its synthetic is_implicit=True / -1 sentinel callables.
• Per-callable code as stored data.
• Raw analysis.json envelope keys.

Signal — the major bump itself. The analyzer pins move in the same release, so v1 payloads and v1 models retire together. Each semantic shift is named in the 2.0.0 CHANGELOG.

Why not a minor with the two layers alongside

Carrying two model layers means carrying two Neo4j reconstruction paths as well, for a payload shape no released analyzer emits any more (codeanalyzer-python 1.4.0, codeanalyzer-typescript 1.2.0 and codeanalyzer-java 3.0.1 all emit canonical v2). The cost is real and ongoing; the benefit accrues only to consumers reaching past the public API, which is the surface the policy deliberately does not protect.

Definition of done

• The policy above is stated in the 2.0.0 CHANGELOG with each semantic shift named. Tracked as a definition-of-done clause on python-sdk v2 model layer: one Node/Edge/Application #309 (leg 1) rather than as separate work — this issue decides, it does not implement.

Closing as decided.