[Java] Embed Rust CLI runtime 4.4: JNA binding interface and implementation

[Copilot]

Implements the NativeBinding interface, JnaNativeBinding JNA-backed implementation, and OutboundCallback JNA callback — the Java bridge to the five copilot_runtime_* C ABI entry points exposed by runtime.node.

New files

• OutboundCallback — JNA @FunctionalInterface Callback; invoked by the native runtime on native threads. Documents that data pointer is only valid during invocation and must be copied with Pointer.getByteArray(0, len).

• NativeBinding — Internal interface abstracting the five ABI entry points. interface (not abstract class) for future FFM swappability via MR-JAR; direct instantiation, no ServiceLoader.

• JnaNativeBinding — JNA implementation:

  • Inner CopilotRuntimeLibrary extends Library mapping copilot_runtime_* exports
  • Library-never-unloads: static volatile loadedLib/loadedPath fields; once set, never cleared in production
  • Duplicate-path guard: loading a different library path throws IllegalStateException with a diagnostic message naming both paths
  • Active-callback tracking: AtomicInteger activeCallbacks incremented on callback entry, decremented on exit — callers must drain to zero before connection_close/host_shutdown
  • Package-private testing constructor (accepts a stub CopilotRuntimeLibrary) and resetForTesting() for unit test isolation

• JnaNativeBindingTest — 24 unit tests: delegation via StubRuntimeLibrary, library load/guard, and callback invocation/tracking against the spike-3-4 libcallback_test native library.

Modified files

• pom.xml — adds net.java.dev.jna:jna:${jna.version} (5.19.1, <optional>true</optional>); version is a Maven property for deliberate upgrades.

• module-info.java — adds requires static com.sun.jna and opens com.github.copilot.ffi to com.sun.jna (required for JNA reflection access to callback interface methods under JPMS).

Usage sketch

// Production path (called by FfiRuntimeHost, task 4.5)
NativeBinding binding = new JnaNativeBinding(NativeRuntimeLoader.resolve());

OutboundCallback cb = (userData, data, len) -> {
    byte[] bytes = data.getByteArray(0, len); // copy before returning
    queueInputStream.enqueue(bytes);
};

int serverId = binding.hostStart(argvJson, argvJson.length, null, 0);
int connId   = binding.connectionOpen(serverId, cb, Pointer.NULL,
                   null, 0, null, 0, null, 0);

• Fixes [Java] Embed Rust CLI runtime 4.4: JNA binding interface and implementation #2146

[Copilot]

Pull request overview

Adds Java’s JNA bridge to the embedded Rust runtime C ABI.

Changes:

• Defines native binding and callback interfaces.
• Implements guarded JNA library loading and ABI delegation.
• Adds JNA configuration and unit tests.

Show a summary per file

File	Description
java/sdk/pom.xml	Adds optional JNA dependency.
java/sdk/src/main/java/module-info.java	Configures JNA module access.
OutboundCallback.java	Defines the native callback contract.
NativeBinding.java	Defines the internal runtime ABI.
JnaNativeBinding.java	Implements JNA loading, delegation, and callback tracking.
JnaNativeBindingTest.java	Tests delegation, loading, guards, and callbacks.

Review details

Suppressed comments (2)

java/sdk/src/main/java/com/github/copilot/ffi/JnaNativeBinding.java:72

• This export returns the runtime's one-byte Rust/C ABI bool (rust/src/ffi.rs:43), but JNA maps Java boolean to a 32-bit C int. That ABI mismatch can decode a native false as true. Use a one-byte native return (or explicit type mapper) and convert it in connectionClose.

        boolean copilot_runtime_connection_close(int connectionId);

java/sdk/src/main/java/com/github/copilot/ffi/JnaNativeBinding.java:69

• This export also returns the runtime's one-byte Rust/C ABI bool (rust/src/ffi.rs:42), whereas JNA's Java boolean mapping expects a 32-bit C int. A native false can therefore be decoded incorrectly. Use a one-byte native return (or explicit type mapper) and convert it in connectionWrite.

        boolean copilot_runtime_connection_write(int connectionId, byte[] data, int dataLen);

• Files reviewed: 6/6 changed files
• Comments generated: 6
• Review effort level: Balanced

[github-actions]

Cross-SDK Consistency Review ✅

All 6 changed files in this PR are scoped entirely to Java (java/sdk/). The changes introduce:

• NativeBinding interface and JnaNativeBinding JNA implementation — internal Java FFI bridge to the Rust CLI runtime's C ABI
• OutboundCallback — JNA-specific callback type
• Maven/JPMS plumbing (pom.xml, module-info.java)

No cross-SDK consistency issues. This is Java-specific native-bridge infrastructure using JNA (Java Native Access), which is a Java ecosystem mechanism with no equivalent in the other SDKs. Each SDK integrates the native runtime through its own platform-appropriate path (Node.js via native modules, Python via ctypes/cffi, Go via cgo, .NET via P/Invoke, Rust natively). No public API surface was added or modified, so no parallel changes are needed in Node.js, Python, Go, .NET, or Rust.

Generated by SDK Consistency Review Agent for #2230 · sonnet46 17.7 AIC · ⌖ 5.39 AIC · ⊞ 6.6K · ◷