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
Closing as decided.
Parent: codellm-devkit/.github#35 · Spec:
docs/design/specs/2026-09-03-python-sdk-canonical-v2.md(#318) § 6Problem
python-sdkcarries four per-language model packages plus per-language facades. Canonical v2's premise is oneNode/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
PythonAnalysis,JavaAnalysis,TypeScriptAnalysis,CAnalysis).PyCallable,JCallable,TSCallable, …) — now subclasses of the shared bases incldk/models/cpg/.Accessors whose v1 return type no longer exists as stored data become computed views over the spine:
get_method_body(sig)slicesmodule.source[callable.span.bytes];get_call_sites(...)readsbody{}entries withkind == "call";get_system_dependency_graph()returns the v2 SDG over identity-only edges.Not preserved — consumers reaching past the public API:
can://ids).JGraphEdgesrich endpoints (source/targetasJMethodDetailobjects)._CALLABLES_LOOKUP_TABLEand its syntheticis_implicit=True/-1sentinel callables.codeas stored data.analysis.jsonenvelope 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-python1.4.0,codeanalyzer-typescript1.2.0 andcodeanalyzer-java3.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
Closing as decided.