Backwards-compatibility policy for the v2 model layer

[rahlk]

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

Skeleton — bodies to be filled in by the maintainer. Not started — filed ahead of pickup.

Problem

python-sdk carries four per-language model packages (cldk/models/{java,python,typescript,c}) plus per-language facades. Canonical v2's premise is one Node / Edge / Application. "Strong backwards compatibility" has to be defined before the new model layer is designed, or the policy becomes whatever the implementation made convenient.

Scope boundary

Decides the policy only. Does not implement the v2 model layer.

Goals

• What of the existing surface is preserved: method surface, return types, or the pydantic model classes themselves
• How deprecation is signalled, and how long the old models keep parsing
• Whether the SDK's next release is a minor (v2 models alongside) or a major (replacing)

Caveats and known risks

• Carrying two model layers until the deprecation window closes is a real maintenance cost — name it rather than absorb it.
• TODO

Definition of done

• TODO