F7: L3/L4 consumption API — shared program-slice engine + five facade verbs (slice/flows/def-use)

[rahlk]

PROBLEM

Schema v2 exposes rich L3/L4 information — per-callable CFG/CDG/DDG and the interprocedural SDG (param_in/param_out/summary) — but F6 (#244) only exposes it as raw nx graphs the user must hand-walk. This issue adds the "easy to consume" derived layer: a shared program-slice engine and five facade verbs that turn the graphs into citable slice/flow evidence.

Design: docs/superpowers/specs/2026-07-14-l3l4-consumption-api-design.md (local).

SCOPE BOUNDARY

Analysis-complete PRIMITIVES only — slices, dataflow reachability, def-use. NO taint/policy layer (sources, sinks, sanitizers, tainted-path search): that is #229 and the 2.1.0 chain's sink_pattern/without_passing_through. No new per-language analysis (the analyzers are pure graph providers). No Cypher-pushdown of traversal (client-side over nx for rc.1; pushdown parallels the chain's #217, later).

GOALS (the contract)

1. Shared engine cldk/graph/engine.py — traversal written ONCE, language-neutral, operating on the cpg models (F2: cldk/models/cpg — canonical schema-v2 models, modeled once (layer 1) #240). Never reimplemented per language (that is the divergence bug class that shipped 4x in the 2026-07-14 audit).
2. ABC data-provider seam on each AnalysisBackend (extending F6's additions): program_graph(callable_uri), sdg_edges(), resolve_location(file,line,col?), source_slice(vertex_uri), callable_of(vertex_uri) — implemented by every Codeanalyzer (local, from cpg) AND every Neo4jBackend (Cypher).
3. Five facade verbs (identical on all four facades, thin delegates to Engine(self.backend)):
   slice_backward, slice_forward, flows_to, def_use, control_deps — signatures per the spec §4.
4. Polymorphic seed: "file:line[:col]" | "can://…@line:col" | BodyNode, normalized by resolve_vertex.
5. Result objects cldk/graph/result.py: GraphResult base (subgraph, evidence[{uri,file_line,code,role}], uris(), explain(), to_json(), len, bool); SliceResult; FlowResult (+ FlowPath == the 2.1.0 chain's PathWitness shape). Confidence read from keystone prov: ssa->structural, points-to->resolved (feat(core-models): edge confidence labels — resolved / structural / unresolved #207 vocab).
6. Capability gating (reuse the epic model): L3 for intra slices/def_use/control_deps, L4 for flows_to/interprocedural. Honest degrade by default (label structural, record gap in explain()), strict=True raises CapabilityError. Java at rc.1 (pre-v2) degrades identically to level-2 — one path, no per-language branch.

CAVEATS AND KNOWN RISKS

• Depends on F2 (F2: cldk/models/cpg — canonical schema-v2 models, modeled once (layer 1) #240 cpg models) and F6 (F6: new surface — entrypoints, L3/L4 accessors, AnalysisLevel L1–L4 #244 raw accessors + AnalysisLevel); sequence after both.
• Location-seeded queries require TypeScript backend does not invalidate cached analysis.json on source change — stale results unless eager=True #269 (TS cache invalidation) or file:line seeds silently rot on TS after an edit — precondition for the TS location-seed path.
• Python L3/L4 edge identity must be can:// end-to-end for interprocedural stitching (codeanalyzer-python#98) — gates the Python leg's flows_to quality.
• interprocedural=None means "as deep as the level allows" (intra at L3, inter at L4); an explicit True on L3 is a capability miss, never a silently-intra answer.

DEFINITION OF DONE

• Engine unit tests on hand-built cpg fixtures assert EXACT expected vertex sets (a backward slice == the hand-computed node set, not "non-empty").
• Dual-backend parity contract: every Tier-1 verb, local vs Neo4j, identical results modulo documented lossiness (Neo4j code=None when source unprojected) — seeds test: generalized cross-language, cross-backend contract suite #210.
• End-to-end assertions against the golden L3/L4 samples from cants and codeanalyzer-python.
• All-new additive surface: F1 oracle records these methods as present; the frozen get_* facade is untouched.

Part of #238

[rahlk]

Implementation plan drafted (local: docs/superpowers/plans/2026-07-14-l3l4-slice-engine.md) — 10 TDD tasks: result objects, provider ABC + resolve_vertex, capability gating, engine (intra slices, flows_to/def_use, interproc depth), local cpg provider mixin, ABC+local wiring x4, Neo4j provider + facade delegates x4, dual-backend parity contract + golden e2e. Execution BLOCKED until F2 (#240) + F6 (#244) land on release/2.0; TS location-seed path additionally needs #269.

[rahlk]

Engine core complete (Tasks 1–6 of 10) — awaiting F2

The L3/L4 slice-engine core is implemented and whole-branch-reviewed on branch feat/issue-270-slice-engine (off release/2.0, not yet pushed). The plan's Tasks 1–6 are cpg-independent (they operate on the ProgramGraphProvider abstraction), so they proceeded now; Tasks 7–10 remain blocked on F2 (#240) — the cldk/models/cpg/ models — and are the wiring layer (local cpg provider, Neo4j provider, facade delegates, parity/e2e).

Built (cldk/graph/, 19 commits, 36 tests green): result objects (SliceResult/FlowResult/FlowPath), the ProgramGraphProvider ABC data-seam, capability gating (honest-degrade + strict), and Engine with all five verbs — slice_backward, slice_forward, flows_to, def_use, control_deps. Traversal is written once over an nx.MultiDiGraph (parallel cfg/cdg/ddg edges); confidence is read from prov (ssa→structural, points-to→resolved); the uris()==subgraph.nodes() invariant holds across all verbs.

Review found and fixed 9 defects (each latent in the plan's own code, none surfaced by passing tests): to_json dropping flow witnesses; a greedy location regex; DiGraph collapsing coincident cfg/ddg edges (→ MultiDiGraph decision); seed-not-in-graph inconsistency; duplicate flows_to witnesses from all_simple_paths over parallels; control-slice dataflow contamination; and — from the whole-branch pass — flows_to gated at L3 not L4, flows_to ignoring the sink's callable (false "no flow"), and the SDG overlay ignoring the edges= filter. Final verdict: ready for scope-complete.

Carry-forward for the wiring tasks (7–10, when F2 lands)

• RISK-A (Important, contract): the flow-hop kind fallback is best.get("kind") or best.get("family"). When the Task-7 local provider materializes the cpg Edge.kind onto intra ddg edges, every intra flows_to hop's kind would silently change from "ddg" to that value, breaking facade-level kind expectations. Task 7–9 must keep hop-kind family-first for intra edges (only family=="sdg" hops report the concrete param_in/param_out/summary kind).
• Deferred interprocedural completeness (needs real L4 analysis.json to validate): def_use interprocedural reach; multi-hop (3+ callable) flows_to (current fix spans source+sink callables); likely a whole-program-graph provider primitive.
• I3 (multi-seed): flows_to/def_use take resolve_vertex(...)[0]; union over all resolved vertices (or record the narrowing in explain()) once real resolve_location multiplicity exists.
• Minor/optional: RISK-B (explicit interprocedural=True + non-ddg edges downgrades with no explain() breadcrumb); I5 truncated covers the path-count cap but not the depth cutoff; verify the _ddg_tier prov mapping against the real keystone analysis.json shapes.

Spec/plan (local, gitignored): docs/superpowers/specs/2026-07-14-l3l4-consumption-api-design.md, docs/superpowers/plans/2026-07-14-l3l4-slice-engine.md.

[rahlk]

Engine core opened as PR #271 → release/2.0 (Tasks 1–6; additive, 36 tests, whole-branch-reviewed). Not to be merged as "F7 done" — Tasks 7–10 (wiring, blocked on F2 #240) complete the feature on the same branch.

[rahlk]

F2 (#240) — the cpg models F7 Tasks 7-10 depend on — is complete and up as PR #274 -> release/2.0 (30 tests, whole-branch reviewed, parses both analyzers L1/L4). Once #274 merges, F7's blocked Tasks 7-10 (local cpg provider, Neo4j provider, facade delegates, parity/e2e) unblock and this engine wires end-to-end. Note the RISK-A hop-kind contract (this issue) and the #273 vocabulary drift (blocks F3, affects F7 accessors on real data) still apply.