[jvm] auto-detect Java SAM interfaces; honor SAM in overload resolution

[kLabz]

Two related changes that together make Haxe match javac's lambda-vs-SAM
(Single Abstract Method) conversion rules on the JVM target.

1. Structural SAM detection in javaModern.ml

Previously, only interfaces carrying @FunctionalInterface were tagged
CFunctionalInterface and so eligible for implicit conversion from a
function value. The annotation is documentation in javac too — what
makes a type lambda-convertible is having exactly one abstract instance
method, per JLS §9.8. The Android SDK rarely annotates its listeners,
which forced every consumer of the JVM target to hand-roll adapter
classes for View.OnClickListener, DialogInterface.OnClickListener,
MediaPlayer.OnCompletionListener and so on.

This patch auto-tags any .jar-imported interface as @:functionalInterface
when it has exactly one abstract instance method, excluding:

• static / default / private / synthetic methods,
• constructors,
• Object members re-declared as abstract (equals/hashCode/toString,
  matched by name+arity since their signatures on j.l.Object are
  unambiguous — JLS §9.8 excludes these from the SAM count).

The explicit @FunctionalInterface annotation path is preserved.

2. SAM-aware overload candidate filtering

overloadResolution.ml's unify_cf used strict Type.unify to filter
candidates before the cast layer could fire. A function value passed to
an overload whose parameter is a SAM class would be discarded at the
filter step. Now, when strict unify fails, the filter retries via the
SAM conversion path — unifying the function's TFun against the SAM
method's signature, mirroring what AbstractCast does at cast time. Only
candidates whose SAM signature actually matches the function shape
survive, so this isn't a blind accept.

Two supporting fixes round this out:

• overloads.ml rate_conv: added a TInst(SAM), TFun case so specificity
  ranking works when two SAM-parametered overloads both accept the
  same function. The rate descends through the SAM method's signature
  rather than raising Not_found, which previously discarded the
  candidate during reduce_compatible.

• tOther.ml get_singular_interface_field and the parallel walker in
  genjvm.ml's check_functional_interface now exclude equals/hashCode/
  toString by name+arity, matching the new exclusion in javaModern so
  interfaces like Comparator (abstract equals re-declared) — and the
  Android SDK's various 'override equals' interfaces — are still
  detected as SAMs at both typer and codegen stages.

Tests:

• tests/unit/.../IssueFunctionalInterfaceOverload.hx exercises the
  overload disambiguation path with two @:functionalInterface
  interfaces of disjoint shape (Int,Int -> Int vs String -> String).
• tests/misc/jvm/projects/StructuralSam/ ships a .java file with six
  interface shapes — plain SAM, abstract-equals re-declaration,
  default/static method skipping, multi-abstract non-SAM, generic-arg
  SAM, and overloaded call sites — none annotated @FunctionalInterface.
  Runs the generated jar end-to-end to verify both type-checking and
  runtime closure-adapter dispatch.

Limitations matching javac:

• Abstract-class SAMs (e.g. android.content.BroadcastReceiver) remain
  unsupported; javac doesn't allow lambda conversion to those either.
• Two SAM-parametered overloads where both signatures would accept
  the same function value remain ambiguous and require explicit
  disambiguation.

[kLabz]

@EliteMasterEric would this help you with your jvm project(s)?

Can you check if your project run into issues with this (either at compile time or runtime) with corresponding nightlies?
https://build.haxe.org/builds/haxe/linux64/haxe_2026-05-14_jvm/SAM_a18560e.tar.gz (or similar path for win/mac)

[Simn]

I understand what we're trying to do here, but it seems a little messy because there's no clear authority on what is and isn't considered a SAM interface. The java loader initially determines it, then the typer basically verifies it via check_functional_interface (which just silently does nothing in the fail-case) and finally the generator checks it again in its own check_functional_interface function. In all three places we dance around this object member special case, which suggests to me that something should be centralized here.

I'm aware that this PR doesn't really introduce this mess and merely amplifies it, but I would still like to look into a cleaner approach here. Having functional_interface_lut on the common context already felt like somewhat of a hack, though it might be a necessary one because we have to store this information somewhere. But adding functional_interfaces_used and relying on the abstract cast filter to populate that? Ugh...

[kLabz]

Claude's answer before implementing

Looking at the diff, the mess concentrates in two axes — what counts as a SAM and which SAMs the program uses. Both can be tightened significantly.

What's actually duplicated

SAM-ness rule appears three times, each with its own copy of the JLS §9.8 Object-member exclusion:

• javaModern.ml — structural detection at load (is_object_redeclaration + abstract/static/etc. filter)
• tOther.ml::get_singular_interface_field — used by overload rating
• genjvm.ml::Preprocessor.check_functional_interface — re-verifies and populates the LUT

Usage tracking appears twice:

• abstractCast.ml writes functional_interfaces_used keyed by @:native path
• genjvm.ml re-walks the whole AST to compute essentially the same set (by class identity)

Proposed cleanup

1. One module owns "is this a SAM, and what's its method?"

Add src/core/functionalInterface.ml (or fold into tOther) exposing exactly:

val is_object_member : tclass_field -> bool        (* JLS §9.8 *)
val sam_method : tclass -> tclass_field option     (* None unless CFunctionalInterface + exactly one non-default, non-Object-member MethNormal *)

Then:

• get_singular_interface_field becomes a thin caller (or is deleted in favor of sam_method).
• check_functional_interface in genjvm becomes match sam_method c with Some cf -> register ... | None -> (). No private is_object_member copy, no re-implementing the count.
• javaModern calls the same helper at the OCaml level too — except it's working on jf records, not tclass_field. The fix there is smaller: keep the structural detector local, but lift is_object_redeclaration + the JDK-internal-package filter behind named helpers in the same module and document them as "the load-time mirror of FunctionalInterface.sam_method."

2. Drop functional_interfaces_used entirely.

The AST scan added in 605467b is a strict superset of what AbstractCast records — an implicit SAM conversion produces a node whose etype is the SAM TInst, so note_fi_in_type already sees it. That makes the abstractCast bookkeeping, the field on common.context, the field on Gctx.t, and the special clone-sharing comment all dead weight. Remove:

• Hashtbl.replace ctx.com.functional_interfaces_used ... in abstractCast.ml (and the @:native re-keying it had to do)
• functional_interfaces_used on common.context and Gctx.t
• the shared-with-parent clone case

Then genjvm's preprocessor has a single authority: walk the AST, collect TInst whose class has CFunctionalInterface, call sam_method to register them. One pass, one rule, one place.

3. Bonus: the overload-resolution helper already lives in the right shape.

try_functional_interface_match in overloadResolution.ml and the new TFun → TInst rate case in overloads.ml are both doing "given a SAM class and a function type, unify against the SAM method." That's sam_method + apply_params + unify — extract it as FunctionalInterface.unify_as_sam : tclass -> tparams -> t -> bool and call it from both sites.

Net effect

After this, the answer to "what is a SAM?" is one function. The answer to "is this SAM used?" is one AST walk in one place. Java loader tags the flag, typer/overload/generator all query through the same helper, and common.context loses a field instead of gaining one.

---

What changed:

• genjvm.ml::check_functional_interface now calls TClass.get_singular_interface_field instead of carrying its own copy of the loop + Object-member rule. JLS §9.8 lives in exactly one place (tOther.ml).
• functional_interfaces_used is gone from common.context, Gctx.t, the to_gctx mapping, the create/clone constructors, and the abstractCast write site (including the @:native re-keying that only existed because of the typing↔generation path mismatch).
• genjvm's preprocessor still has the AST scan (the actual source of truth) but no longer has the note_if_used_fi / Hashtbl.mem branch.

The reviewer's three concerns:

1. No clear authority on what is/isn't a SAM — now one helper, called from all three sites (typeloadFields, overloadResolution, overloads, genjvm).
2. functional_interface_lut felt like a hack — untouched; it's the cache for the SAM-method lookup. Could be argued either way but it's not amplified.
3. functional_interfaces_used populated by abstractCast — deleted entirely.

The remaining structural-detection code in javaModern.ml is appropriately local: it works on jf records before tclass_fields exist, so it can't share the helper.

[Simn]

Much better!

One thing I'm slightly worried about is List.memqing into fi_used_classes in genjvm.ml. This is a linear lookup and we do it for every class, so it's technically O(n^2). This might not matter in practice because the element count in fi_used_classes is going to be much lower, but I think it's still better to look this up via a Hashtbl with the cl_path key.

[kLabz]

Claude seems to think the whole functional_interface_lut thing is (and was already) pretty much useless.. I tried to make it look at the whole thing instead of focusing only on this PR, but it insists. What do you think?

CI seems ok with removing it, at least (commit / CI run).

Should I cherry-pick that commit here?

[Simn]

but typeloadModule's @:functionalInterface path never populated it

I don't understand that part because check_functional_interface had ctx.com.functional_interface_lut#add c.cl_path (c,cf).

[kLabz]

It got confused about #11549 somehow, but still insists the lut wasn't doing much:

The cached computation is a walk over a SAM interface's field list —
typically under 10 entries, and short-circuits on the second non-default
method, so the perf delta from recomputing is well below noise. Doing
that directly in AbstractCast collapses the two load paths into one and
removes the field from common.context.

[kLabz]

I'm getting it to benchmark the change with pessimistic scenarios, and it quickly hit the JVM method-size limit instead 😅

  ┌─────────────────────────────────┬────────────────────────────┬─────────────────────────┬──────────────┐
  │            benchmark            │ before (cbd81b1, with LUT) │ after (ee67399, no LUT) │    ratio     │
  ├─────────────────────────────────┼────────────────────────────┼─────────────────────────┼──────────────┤
  │ single SAM (10k → Runnable)     │ 1.596 ± 0.059 s            │ 1.635 ± 0.146 s         │ 1.02× ± 0.10 │
  ├─────────────────────────────────┼────────────────────────────┼─────────────────────────┼──────────────┤
  │ mixed SAMs (6 distinct classes) │ 1.957 ± 0.024 s            │ 1.987 ± 0.068 s         │ 1.02× ± 0.04 │
  └─────────────────────────────────┴────────────────────────────┴─────────────────────────┴──────────────┘

Both ~2% slower on after, but σ overlap on the single case is huge (±9% on the after run) and the mixed case 
is right at the noise floor. No meaningful regression — exactly what we'd predict from "swap a hash lookup for
a 5-element list walk." Cache wasn't load-bearing.

[Simn]

Yes I think this is fine, the argument just didn't seem accurate.

One last cosmetic change I'd like to make is to have that note_fi stuff in genjvm become its own function (in the Preprocessor module) returning the list instead of being awkwardly added to the preprocess function.

[kLabz]

Something like that?
kLabz@00d9484

[Simn]

The standalone diff looks a bit strange but I think that's right.

[kLabz]

Looks better in the PR diff indeed :)