feat: @ExternalType adapter generator for provided-style extensions

[jbachorik]

Stacked on top of #791. This PR targets the jb/configurations branch so it shows only the incremental diff. Once #791 merges, this can be rebased onto develop.

Rationale

Provided-style extension impls (introduced in #791) currently reach into application types via hand-written MethodHandleCache adapters. That works but has three ergonomic costs:

• String method names. mh.findVirtual(cls, "jobId", int.class) is not refactor-safe and IDE tooling can't check it.
• Eager-resolution foot-gun. static final MethodHandle fields fail extension init if the target class isn't yet visible on TCCL.
• Boilerplate per call site. Every reflective access expands into 5+ lines of try/catch, type wiring, and cache plumbing.

Solution

@ExternalType("com.example.app.Real") on an interface + a build-time annotation processor → generated $Ext adapter with typed static dispatchers, per-method lazy volatile MethodHandle resolution, and no cache lookup on the warm path.

Quick Start

Declare the interface in the extension's api source set:

@ExternalType("org.apache.spark.scheduler.SparkListenerJobStart")
public interface JobStart {
  int jobId();
  long time();
}

Use the generated adapter from the impl:

int id = JobStart$Ext.jobId(event);
long ts = JobStart$Ext.time(event);

The org.openjdk.btrace.extension Gradle plugin auto-registers the processor on the api source set — no extra wiring needed.

See the migrated btrace-spark example (btrace-extensions/examples/btrace-spark/src/impl/java/.../SparkApiImpl.java) for a before/after in a real extension.

Scope

In v1:

• Virtual + static method adapters (@ExternalType.Static for statics)
• Primitive and reference return / parameter types
• Lazy resolution via receiver defining loader (virtual) or TCCL (static)
• Generic types erased to raw forms for MethodType literals
• Compile-time validation (non-interface targets, empty value → clear error)

Not in v1 (use ClassLoadingUtil / MethodHandleCache directly):

• Field access
• Constructors
• instanceof / checkcast on external types
• Chained @ExternalType references
• Non-public method visibility

Test Plan

• Unit: annotation retention + @Static targeting (ExternalTypeAnnotationTest)
• Unit: processor detects annotated interfaces (ExternalTypeProcessorTest.generatesAdapterForAnnotatedInterface)
• Unit: method dispatcher signatures (generatedAdapterContainsDispatchersForEachMethod)
• Unit: virtual dispatcher shape (virtualDispatcherUsesLazyMethodHandle)
• Unit: static dispatcher uses TCCL (staticDispatcherUsesTccl)
• Runtime smoke: compile + load + invoke generated adapter (generatedAdapterInvokesRealMethod)
• Unit: validation errors for invalid targets (rejectsAnnotationOnClass, rejectsEmptyValue)
• Unit: parameterized types produce raw type literals (generatedAdapterHandlesParameterizedTypes)
• Integration: in-tree Spark example migrated from MethodHandleCache to @ExternalType — builds end-to-end through the Gradle plugin

🤖 Generated with Claude Code

---

This change is