Java/Kotlin lambda → functional-interface (SAM) extraction + synthesis

[colbymchenry]

Context

Surfaced during the playbook validation for #412 (JVM FQN imports + anonymous-class extraction). The anon-class extraction closed a significant guava read gap (CacheBuilder: 1.5 → 0 Read in agent A/B), but Splitter.on(...).split()-style flows still drive 2–3 Reads per agent run because lambdas passed to constructors are not in the graph at all.

The hole

Guava (and any Java 8+ functional-interface usage) does:

return new Splitter(
    (splitter, toSplit) ->
        new SplittingIterator(splitter, toSplit) {
          @Override int separatorStart(int s) { ... }
        });

The lambda (splitter, toSplit) -> ... IS Strategy.iterator for this Splitter instance — it's the body the runtime jumps to when strategy.iterator(this, seq) runs in splittingIterator. Static extraction currently treats lambda_expression as a no-op pass-through, so:

• Strategy.iterator (the SAM interface method) has zero implementations in the graph.
• trace(splittingIterator, separatorStart) fails at the strategy.iterator(...) hop — no callees.
• An agent investigating that flow Reads Splitter.java to manually link on() → lambda → anon SplittingIterator.

#412's anon-class extraction picks up the new SplittingIterator() { ... } inside the lambda (so the override is in the graph), but the lambda itself is not — so the chain still breaks at Strategy.iterator.

Proposed mechanism

1. Extract lambda_expression (Java) and arrow_function/function_expression argument lambdas as method nodes named <lambda@line>, scoped under the enclosing method via the existing nodeStack.
2. At synthesis time, bind each lambda to a SAM type: walk up to the enclosing call/object_creation_expression, look up the called constructor or method's signature, take the parameter type at the lambda's argument position, and check if that type is a single-abstract-method interface (sole abstract method in its body). If so, synthesize a calls edge from the SAM method → the lambda's body, tagged provenance:'heuristic', synthesizedBy:'lambda-sam'.
3. Method references (Class::method, obj::method) extend the same mechanism — bind the referenced method to the SAM target.

The existing IFACE_OVERRIDE_LANGS interface-impl synthesizer can be reused for the linking step once lambdas have an implements edge to the SAM interface.

Validation target (playbook)

A re-run of the guava agent A/B should drop Splitter q3 with-arm reads from 2.5 → ~0 and CacheBuilder q2 should stay at 0. Spring repos (petclinic-kt, mall) must remain at 0/0 — no regression. No node explosion (a sanity check on mall's 22,861 node count).

Risks / scope notes

Per docs/design/dynamic-dispatch-coverage-playbook.md: "partial coverage is WORSE than none." If the SAM binding misses the case where the lambda body itself constructs an anon class (the guava (s, t) -> new SplittingIterator() { ... } pattern), we'd surface a dead-end Strategy.iterator → <lambda> edge with no further bridge to separatorStart. The end-to-end test must verify a 4+ hop trace lands on the override body, not just the lambda.

Cost is a real extractor change (lambdas become nodes, signature lookup is new at synthesis time) — probably a 3–6 hour PR plus playbook validation.

[colbymchenry]

Closing as not actionable via extraction-layer.

What I tried

Implemented the full mechanism described in the issue body on a branch (feat/lambda-sam-synthesis, since deleted):

• Java lambda_expression extracted as a <lambda@line:col> method node, scoped under the enclosing method (qualifiedName Class::method::<lambda@…>). Limited to constructor-arg lambdas (new Foo(s -> …)) to avoid 5,400 method-arg lambda nodes (e.g. .map(x -> …)) polluting search/explore output — the synth can't bridge those without receiver-type tracking that's out of scope here.
• nodes.metadata JSON column (schema migration v5) stores each lambda's call-site info ({ parentKind, parentName, argIndex }) so the synth doesn't need to re-walk the AST.
• lambda-sam synthesizer in callback-synthesizer.ts resolves the parent type, finds the constructor whose parameter at argIndex is a SAM interface (parsing the extractor's stored signature), and emits a calls edge from SAMInterface.method → <lambda@…> tagged synthesizedBy: 'lambda-sam'.
• Post-BFS sweep in findRelevantContext pulls synthesized edges into the explore subgraph (the standard BFS exhausts its per-entry depth budget on huge classes' contained members before reaching synth edges 3 hops away).
• "Dynamic dispatch (synthesized — actual runtime targets)" section in the explore Relationships output, labeled with [lambda-sam @file:line] so the agent recognizes the runtime target.

Structural correctness — verified

• 70 constructor-arg lambdas extracted in google/guava (down from the 5,499 if all lambda kinds were extracted).
• 9 lambda-SAM edges synthesized in guava — Splitter::Strategy::iterator correctly bridges to all four Splitter.on() lambdas at lines 143, 171, 219, 274 (×2 for the android/guava + guava mirror dirs).
• codegraph_node "Splitter::Strategy::iterator" trail now lists the four lambdas as Calls → targets.
• codegraph_explore Relationships output surfaces the Dynamic dispatch section with the SAM bridge.
• 3 new tests pass (extraction + integration); full suite stays at 1073/1075.

Agent A/B — does not pay off

Per-question with-arm reads, n=2 runs, claude-opus headless (the playbook's exact methodology):

Repo / Q	Baseline (post-#412 anon-class)	+ full lambda-SAM + sweep + dyn-dispatch	Δ
guava q1 (ImmutableList)	35s / 1.0r / 1.0g	33s / 1.0r / 1.0g	flat
guava q2 (CacheBuilder)	50s / 0.0r / 0.0g	60s / 1.0r / 0.0g	+1 read, +10s
guava q3 (Splitter)	57s / 2.5r / 0.0g	58s / 2.0r / 0.0g	−0.5 reads
petclinic-kt q1	25.8s / 0.0r / 0.0g	30s / 0.5r / 0.0g	regression
mall q3	32.5s / 0.0r / 0.0g	25s / 0.0r / 0.0g	clean

Issue's stated goal was "guava q3 reads from 2.5 → ~0". Best result was 2.0 (small win), bought at the cost of a 1-read regression on guava q2 and 0.5-read regression on petclinic-kt q1. Tool-call counts went up across the board (the agent uses the new info — codegraph_node calls on the lambdas appeared in the sequences — but still Reads to verify).

Why this is a wall, not a bug

The CLAUDE.md playbook doctrine: "ADAPT the tool to the agent — DON'T try to change the agent." This work passes the structural-correctness bar (lambdas in graph, SAM bindings correct, surfaced in codegraph_node and in explore output). The agent uses the new edges. It still Reads.

The Reads on guava aren't about missing edges; they're about claude-opus's "verify by Read" pattern on Java library code with anonymous strategy classes. Adding more precise structural data doesn't change that pattern. The playbook's own warning applies: "partial coverage is WORSE than none. Bridging one boundary but not the next reveals a hop the agent then drills + reads to finish." — and that's what's happening: lambda-SAM bridges to the lambda body, but the agent still wants to see the surrounding code to confirm.

What's not closed by this verdict

Splitter::Strategy::iterator → <lambda@143> IS a real coverage gap structurally, and the work I did fixes it. If future agent versions (or downstream tooling) end up using the trail more, this is real value left on the table. But the goal as written ("drop guava q3 reads to ~0") is unreachable from the extraction layer alone — it needs the agent to change its verify-by-Read pattern, which is outside our control.

Branch deleted, no PR opened. Posting this so the next time someone considers this work, they have the data.