feat(java): add JNA binding interface and implementation (task 4.4)

- Add JNA 5.19.1 as optional dependency to java/sdk/pom.xml
  with jna.version property for deliberate upgrades
- Create OutboundCallback.java: JNA Callback interface for
  native-to-Java outbound data delivery
- Create NativeBinding.java: interface abstraction for the 5
  copilot_runtime_* C ABI entry points
- Create JnaNativeBinding.java: JNA implementation with
  static singleton (library-never-unloads pattern), duplicate
  path guard, and active-callback AtomicInteger tracking
- Create JnaNativeBindingTest.java: 24 unit tests covering
  delegation, loading, duplicate guard, and callback behavior
  using the spike-3-4 test native library
- Update module-info.java: requires static com.sun.jna,
  opens com.github.copilot.ffi to com.sun.jna

Co-authored-by: edburns <75821+edburns@users.noreply.github.com>

Author: Copilot

java/sdk/pom.xml

@@ -62,6 +62,8 @@
         <surefire.jvm.args />
         <!-- Override parent: the sdk module IS published to Maven Central. -->
         <maven.deploy.skip>false</maven.deploy.skip>
+        <!-- JNA version — pin deliberately; a JNA upgrade must rerun the callback spike. -->
+        <jna.version>5.19.1</jna.version>
     </properties>
 
     <dependencies>
@@ -90,6 +92,18 @@
             <scope>provided</scope>
         </dependency>
 
+        <!--
+            JNA — required only when using InProcess transport. Optional so that
+            subprocess-only consumers do not receive JNA transitively.
+            Pin the version; a JNA upgrade must rerun the callback spike.
+        -->
+        <dependency>
+            <groupId>net.java.dev.jna</groupId>
+            <artifactId>jna</artifactId>
+            <version>${jna.version}</version>
+            <optional>true</optional>
+        </dependency>
+
         <!-- Test dependencies -->
         <dependency>
             <groupId>org.junit.jupiter</groupId>

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

@@ -0,0 +1,212 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+
+package com.github.copilot.ffi;
+
+import com.sun.jna.Library;
+import com.sun.jna.Native;
+import com.sun.jna.Pointer;
+
+import java.nio.file.Path;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.logging.Logger;
+
+/**
+ * JNA-backed implementation of {@link NativeBinding}.
+ *
+ * <p>
+ * Loads the {@code runtime.node} native library by absolute path and delegates
+ * each {@link NativeBinding} method to the corresponding
+ * {@code copilot_runtime_*} C ABI export.
+ *
+ * <h2>Library-never-unloads pattern</h2>
+ * <p>
+ * The loaded JNA library handle is held in a {@code static} field and is never
+ * released. Native worker threads spawned by the runtime outlive any individual
+ * {@code FfiRuntimeHost} instance; unloading the library while those threads
+ * are active would cause a crash. This mirrors the Rust runtime's own
+ * {@code OnceLock<Mutex<HashMap<PathBuf, &'static Library>>>} pattern.
+ *
+ * <h2>Duplicate-load guard</h2>
+ * <p>
+ * Loading a library from a <em>different</em> absolute path in the same JVM
+ * process is rejected with {@link IllegalStateException}. Loading from the
+ * <em>same</em> path more than once is silently accepted.
+ *
+ * <h2>Active-callback tracking</h2>
+ * <p>
+ * The {@link #activeCallbacks} counter is incremented when the native runtime
+ * enters the outbound callback and decremented when the callback returns.
+ * Callers (e.g. {@code FfiRuntimeHost}) must drain this counter to zero before
+ * calling {@link #connectionClose} or {@link #hostShutdown}.
+ *
+ * <h2>GraalVM Native Image</h2>
+ * <p>
+ * JNA callback upcalls are not supported under GraalVM Native Image. InProcess
+ * transport is not available in native-image executables; use subprocess
+ * transport instead.
+ */
+final class JnaNativeBinding implements NativeBinding {
+
+    private static final Logger LOG = Logger.getLogger(JnaNativeBinding.class.getName());
+
+    /**
+     * JNA inner interface mapping the five {@code copilot_runtime_*} C ABI exports.
+     */
+    interface CopilotRuntimeLibrary extends Library {
+        /** Corresponds to {@code copilot_runtime_host_start}. */
+        int copilot_runtime_host_start(byte[] argvJson, int argvJsonLen, byte[] envJson, int envJsonLen);
+
+        /** Corresponds to {@code copilot_runtime_host_shutdown}. */
+        boolean copilot_runtime_host_shutdown(int serverId);
+
+        /** Corresponds to {@code copilot_runtime_connection_open}. */
+        int copilot_runtime_connection_open(int serverId, OutboundCallback callback, Pointer userData, byte[] extSource,
+                int extSourceLen, byte[] extName, int extNameLen, byte[] connToken, int connTokenLen);
+
+        /** Corresponds to {@code copilot_runtime_connection_write}. */
+        boolean copilot_runtime_connection_write(int connectionId, byte[] data, int dataLen);
+
+        /** Corresponds to {@code copilot_runtime_connection_close}. */
+        boolean copilot_runtime_connection_close(int connectionId);
+    }
+
+    // -------------------------------------------------------------------------
+    // Process-wide singleton — never unloaded
+    // -------------------------------------------------------------------------
+
+    private static final Object LOAD_LOCK = new Object();
+
+    /** Absolute path of the library that was first loaded into this JVM process. */
+    private static volatile Path loadedPath;
+
+    /** The loaded JNA library interface. Never released after first set. */
+    private static volatile CopilotRuntimeLibrary loadedLib;
+
+    // -------------------------------------------------------------------------
+    // Instance state
+    // -------------------------------------------------------------------------
+
+    /**
+     * The library interface used by this instance for all delegated calls.
+     *
+     * <p>
+     * For the production path ({@link #JnaNativeBinding(Path)}), this is always the
+     * same object as {@link #loadedLib} (the static singleton). For the test path
+     * ({@link #JnaNativeBinding(CopilotRuntimeLibrary)}), this may be a stub or
+     * mock without modifying the static singleton.
+     */
+    private final CopilotRuntimeLibrary lib;
+
+    /**
+     * Count of callbacks currently executing on native threads. Must reach zero
+     * before {@link #connectionClose} or {@link #hostShutdown} is called.
+     */
+    final AtomicInteger activeCallbacks = new AtomicInteger(0);
+
+    // -------------------------------------------------------------------------
+    // Constructors
+    // -------------------------------------------------------------------------
+
+    /**
+     * Loads (or re-uses) the native library at the given absolute path.
+     *
+     * @param libraryPath
+     *            absolute path to the {@code runtime.node} native library
+     * @throws IllegalStateException
+     *             if a <em>different</em> library path has already been loaded in
+     *             this JVM process
+     */
+    JnaNativeBinding(Path libraryPath) {
+        Path absPath = libraryPath.toAbsolutePath().normalize();
+        synchronized (LOAD_LOCK) {
+            if (loadedLib == null) {
+                LOG.fine(() -> "Loading native library from: " + absPath);
+                loadedLib = Native.load(absPath.toString(), CopilotRuntimeLibrary.class);
+                loadedPath = absPath;
+                LOG.fine(() -> "Native library loaded: " + absPath);
+            } else if (!absPath.equals(loadedPath)) {
+                throw new IllegalStateException("An in-process FFI runtime library is already loaded from '"
+                        + loadedPath + "'; loading a different library from '" + absPath
+                        + "' in the same process is not supported.");
+            }
+        }
+        this.lib = loadedLib;
+    }
+
+    /**
+     * Testing constructor — accepts a pre-built {@link CopilotRuntimeLibrary}
+     * directly, bypassing disk I/O and the static singleton guard.
+     *
+     * <p>
+     * This constructor is package-private and intended solely for unit tests.
+     *
+     * @param library
+     *            a {@link CopilotRuntimeLibrary} stub or mock for testing
+     */
+    JnaNativeBinding(CopilotRuntimeLibrary library) {
+        // Testing seam — skip the static singleton guard.
+        this.lib = library;
+    }
+
+    // -------------------------------------------------------------------------
+    // NativeBinding delegation
+    // -------------------------------------------------------------------------
+
+    @Override
+    public int hostStart(byte[] argvJson, int argvJsonLen, byte[] envJson, int envJsonLen) {
+        return lib.copilot_runtime_host_start(argvJson, argvJsonLen, envJson, envJsonLen);
+    }
+
+    @Override
+    public boolean hostShutdown(int serverId) {
+        return lib.copilot_runtime_host_shutdown(serverId);
+    }
+
+    @Override
+    public int connectionOpen(int serverId, OutboundCallback callback, Pointer userData, byte[] extSource,
+            int extSourceLen, byte[] extName, int extNameLen, byte[] connToken, int connTokenLen) {
+        // Wrap the caller's callback to maintain active-callback tracking.
+        OutboundCallback tracked = (ud, data, len) -> {
+            activeCallbacks.incrementAndGet();
+            try {
+                callback.invoke(ud, data, len);
+            } finally {
+                activeCallbacks.decrementAndGet();
+            }
+        };
+        return lib.copilot_runtime_connection_open(serverId, tracked, userData, extSource, extSourceLen, extName,
+                extNameLen, connToken, connTokenLen);
+    }
+
+    @Override
+    public boolean connectionWrite(int connectionId, byte[] data, int dataLen) {
+        return lib.copilot_runtime_connection_write(connectionId, data, dataLen);
+    }
+
+    @Override
+    public boolean connectionClose(int connectionId) {
+        return lib.copilot_runtime_connection_close(connectionId);
+    }
+
+    // -------------------------------------------------------------------------
+    // Testing support
+    // -------------------------------------------------------------------------
+
+    /**
+     * Resets the process-wide static state for unit tests.
+     *
+     * <p>
+     * <strong>Must only be called from test code.</strong> Resets
+     * {@link #loadedPath} and {@link #loadedLib} so that a subsequent
+     * {@link #JnaNativeBinding(Path)} call can load a different library. In
+     * production, the library is never unloaded.
+     */
+    static void resetForTesting() {
+        synchronized (LOAD_LOCK) {
+            loadedPath = null;
+            loadedLib = null;
+        }
+    }
+}

java/sdk/src/main/java/com/github/copilot/ffi/NativeBinding.java

@@ -0,0 +1,131 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+
+package com.github.copilot.ffi;
+
+import com.sun.jna.Pointer;
+
+/**
+ * Internal abstraction over the Copilot runtime C ABI.
+ *
+ * <p>
+ * Defines the five {@code extern "C"} entry points exposed by the native
+ * {@code runtime.node} library. The JNA-backed implementation
+ * ({@link JnaNativeBinding}) delegates to these through JNA. A future FFM
+ * implementation may be substituted via the multi-release JAR mechanism without
+ * changing callers.
+ *
+ * <p>
+ * All classes in {@code com.github.copilot.ffi} are internal; consumers must
+ * not reference them directly.
+ *
+ * <h2>C ABI entry points</h2>
+ * <ul>
+ * <li>{@code copilot_runtime_host_start} — start the runtime host</li>
+ * <li>{@code copilot_runtime_host_shutdown} — shut down the runtime host</li>
+ * <li>{@code copilot_runtime_connection_open} — open a bidirectional
+ * connection</li>
+ * <li>{@code copilot_runtime_connection_write} — write a JSON-RPC frame to the
+ * runtime</li>
+ * <li>{@code copilot_runtime_connection_close} — close a connection</li>
+ * </ul>
+ *
+ * <h2>Wire format</h2>
+ * <p>
+ * All frames use LSP {@code Content-Length} header framing, identical to the
+ * stdio transport. No special encoding or decoding is needed at the FFI
+ * boundary.
+ */
+interface NativeBinding {
+
+    /**
+     * Starts the runtime host.
+     *
+     * <p>
+     * Blocks for up to ~30 s while the worker boots and connects back. Must not be
+     * called on an async/reactive executor thread.
+     *
+     * @param argvJson
+     *            UTF-8 JSON array of strings: the entrypoint and required flags
+     * @param argvJsonLen
+     *            byte length of {@code argvJson}
+     * @param envJson
+     *            UTF-8 JSON object of environment overrides, or {@code null} when
+     *            empty
+     * @param envJsonLen
+     *            byte length of {@code envJson}, or {@code 0} when {@code envJson}
+     *            is null
+     * @return server handle ({@code 0} on failure)
+     */
+    int hostStart(byte[] argvJson, int argvJsonLen, byte[] envJson, int envJsonLen);
+
+    /**
+     * Shuts down the runtime host.
+     *
+     * @param serverId
+     *            non-zero server handle returned by {@link #hostStart}
+     * @return {@code true} on success
+     */
+    boolean hostShutdown(int serverId);
+
+    /**
+     * Opens a bidirectional connection and registers the outbound data callback.
+     *
+     * <p>
+     * The {@code extSource}, {@code extName}, and {@code connToken} parameters are
+     * reserved extension points. All current SDK implementations pass
+     * {@code null}/0 for all three.
+     *
+     * @param serverId
+     *            non-zero server handle returned by {@link #hostStart}
+     * @param callback
+     *            JNA callback invoked by the runtime on native threads when
+     *            outbound data is available; must be held as a strong reference by
+     *            the caller
+     * @param userData
+     *            opaque cookie passed back to {@code callback} unchanged; pass
+     *            {@link Pointer#NULL}
+     * @param extSource
+     *            reserved; pass {@code null}
+     * @param extSourceLen
+     *            byte length of {@code extSource}; pass {@code 0}
+     * @param extName
+     *            reserved; pass {@code null}
+     * @param extNameLen
+     *            byte length of {@code extName}; pass {@code 0}
+     * @param connToken
+     *            reserved; pass {@code null}
+     * @param connTokenLen
+     *            byte length of {@code connToken}; pass {@code 0}
+     * @return connection handle ({@code 0} on failure)
+     */
+    int connectionOpen(int serverId, OutboundCallback callback, Pointer userData, byte[] extSource, int extSourceLen,
+            byte[] extName, int extNameLen, byte[] connToken, int connTokenLen);
+
+    /**
+     * Writes a JSON-RPC frame to the runtime.
+     *
+     * <p>
+     * The native side copies the buffer synchronously before returning; the byte
+     * array does not need to survive past this call.
+     *
+     * @param connectionId
+     *            non-zero connection handle returned by {@link #connectionOpen}
+     * @param data
+     *            frame bytes
+     * @param dataLen
+     *            byte length of {@code data}
+     * @return {@code true} on success
+     */
+    boolean connectionWrite(int connectionId, byte[] data, int dataLen);
+
+    /**
+     * Closes a connection.
+     *
+     * @param connectionId
+     *            non-zero connection handle returned by {@link #connectionOpen}
+     * @return {@code true} on success
+     */
+    boolean connectionClose(int connectionId);
+}