F2: cldk/models/cpg — canonical schema-v2 models, modeled once (layer 1)

[rahlk]

PROBLEM

The SDK has no models for canonical schema v2. This issue adds layer 1 of the two-layer device: the schema modeled ONCE in cldk/models/cpg/, validating v2 analysis.json for every language.

SCOPE BOUNDARY

Parsing/validation layer only — no compat views (F3), no backend invocation changes (F4), no Neo4j (F5). Build against REAL sample analysis.json files from cants and codeanalyzer-python 0.4.x at each max_level, not against keystone prose.

GOALS

1. Envelope model: schema_version, language, max_level (authoritative — read, never sniff), k_limit, analyzer{name,version}, application.
2. Application (id, symbol_table, call_graph, param_in, param_out), Module (with whole-file source, imports, types{}, functions{}, content_hash), one open-kind Node (string kind, not a rigid Literal union), Edge ({src,dst,...}; the list name IS the type), Span with byte offsets.
3. _NullSafeBase throughout (Go/Rust/C serialize empty collections as null).
4. Accepts sanctioned open-vocabulary prov extensions (e.g. reaching-defs, chore: formalize reaching-defs ddg prov token (+ python-sdk lockstep) codeanalyzer-typescript#32; absorbs feat: accept reaching-defs ddg prov token from codeanalyzer-typescript #232).
5. The L1 ⊆ L2 ⊆ L3 ⊆ L4 superset gate as a test over the level-series samples.

CAVEATS AND KNOWN RISKS

• Analyzer tails are still moving (TS hardening, py stage 5): validate against pinned sample artifacts checked into fixtures, refreshed deliberately.
• Absent = no fact (no null), except the sanctioned callee: null -> id refinement slot.

DEFINITION OF DONE

• Samples from both analyzers at every available level parse and validate.
• Superset gate green across the level series.
• A payload with wrong/missing schema_version fails with an actionable error.

Part of #238

[rahlk]

Precondition cleared: codeanalyzer-python is now schema-v2 conformant (codeanalyzer-python#98 verified resolved on mainline — src/dst/prov edges, can:// identity throughout, types/callables containment, populated param_in/out). So F2's cpg models can validate against real samples from BOTH analyzers now (cants + codeanalyzer-python local builds); only the pin waits on a conformant 0.4.x release (lockstep, F4 #242).

[rahlk]

Implementation plan drafted (local: docs/superpowers/plans/2026-07-14-cpg-models.md) — 6 TDD tasks: _NullSafeBase+Span, Edge+Import, open-kind Node, Module/Application/Analyzer/AnalysisPayload+exports, real-sample validation against BOTH analyzers (L1+L4) + L1⊆L4 superset gate, and the F7/F3 accessor contract. Key design constraints baked in: extra='allow' (one model set parses every language's extras — the opposite of the old per-language extra='forbid'), _NullSafeBase (null-collection coercion for Go/Rust/C), open-kind Node. Executing subagent-driven.

[rahlk]

Whole-branch review surfaced a cross-repo finding filed as #273: the cpg models are keystone-faithful and parse both analyzers, but several canonical fields (base_types/interfaces, fields, metrics) end up EMPTY on real data because the analyzers emit non-keystone names (base_classes/implements_types, attributes, cyclomatic_complexity). Analyzer-side conformance / keystone reconciliation — does NOT block F2 (models are correct), but BLOCKS F3 (#241) views before they map those fields. Also folds in the nested-types question (keystone uses flat type.nesting, not a Node.types container).