perf(engine): detach call-stack ASTs at leaveFile + self-contained heap harness

[n1ckl0sk0rtge]

Summary

Stops com.ibm.engine.callstack from pinning whole-file ASTs for the entire scan, and adds a self-contained harness that proves it.

On large scans the call-stack retained a CallContext per matched invocation for the whole project; each held a live sonar-java Tree, and any Tree pins its file's full AST (parent chain → CompilationUnitTree). Measured on a near-full keycloak scan: ~179k CallContexts driving the heap to ~7 GB, growing linearly and unbounded.

What changed

AST-detach mechanism (detach at leaveFile, not at record time)

• CallContext is now a sealed interface: RetainedCall(tree, scanContext, detachedForm?) / DetachedCall (tree-free: match keys + pre-resolved ArgSnapshots + AST-free DetachedScanContext).
• Detachable calls (Java method invocation, no NEW_ARRAY arg) get a DetachedCall pre-built while the file is live; at leaveFile the retained entry is swapped for it, so the file's AST becomes GC-eligible while cross-file matching continues from the snapshot.
• Same-file detections still fire during their file's analysis on the live RetainedCall, so their SonarQube issues are unaffected. Cross-file detached detections report via the internal SonarComponents.reportIssue (shared per-scan, pins no AST).

Performance/heap harness (this session)

• CallContextStats + callContextStats() accessor threaded CallStackAgent → Handler → ILanguageSupport → JavaLanguageSupport — read-only introspection of retained-with-tree vs. detached counts.
• CryptoCorpusGenerator — generates N synthetic cross-file crypto wrapper/caller unit pairs (JCA APIs) into a temp dir.
• CallStackHeapPerfTest (@Tag("performance"), excluded from the default build via surefire excludedGroups) — generates → compiles to a classpath dir → scans via CheckVerifier so types resolve and detections fire → asserts detachedRatio high and retainedWithTree bounded (deterministic; no heap-MB flake) → reports heap delta + wall-time for manual soak runs.

Run it: mvn test -pl java -DexcludedGroups= -Dtest=CallStackHeapPerfTest (add -Dperf.corpus.files=3000 for a heavy soak).

Verification

• Full default build green: 163 tests, 0 failures (perf test excluded as designed).
• Harness on feat/callstack-ast-detach (200 files): retainedWithTree=0 detached=367 ratio=1.000 — every recorded call detached.
• Discriminator validated: with detachCallsForFile neutralized, the harness fails (retainedWithTree=300 ratio=0.000), confirming the assertion catches AST-pinning regressions.

Design / plan docs

• docs/superpowers/specs/2026-07-06-callstack-heap-perf-harness-design.md
• docs/superpowers/plans/2026-07-06-callstack-heap-perf-harness.md
• docs/superpowers/plans/2026-07-05-callstack-hooks-heap-reduction.md (the ~7 GB measurement)

Note

This does not reproduce the full-project ~7 GB number in CI — that remains the documented manual mvn sonar:sonar keycloak route. The harness targets the engine mechanism at a scaled, deterministic level.