Skip to content

adr-007-native-bundling-strategy.md

Latest commit

 

History

History
398 lines (289 loc) · 39.4 KB

adr-007-native-bundling-strategy.md

File metadata and controls

398 lines (289 loc) · 39.4 KB
Raw

ADR-007: Native runtime bundling strategy — per-platform classifier JARs

Context and Problem Statement

The Copilot SDK for Java currently has no embedded runtime. It depends on an externally provided runtime process (see epic #1917). The ongoing Rust port of the copilot-agent-runtime repository is reaching the point where the runtime can be consumed as a native shared library without requiring a Node.js process, making it practical to embed the runtime directly in the SDK JAR.

The runtime artifact

The artifact to be embedded is runtime.node, a Rust cdylib produced by the src/runtime crate in github/copilot-agent-runtime using the napi-rs build toolchain. Despite the .node file extension (a naming convention of napi-rs), this is an ordinary platform-specific shared library (.so on Linux, .dylib on macOS, .dll on Windows). It exposes two front doors built over the same internal engine:

  • napi front door — loaded by a Node.js process as a native addon (current CLI path).

  • C ABI front door — a fixed set of 5 extern "C" lifecycle and transport entry points that any language can call in-process via FFI (JNA for Java, Python/cffi, C#/DllImport, Go/purego) without a Node.js process. All API methods travel as JSON-RPC data through this fixed transport; the export list never changes as the method set grows. The 5 entry points are:

    Entry point C signature Purpose
    copilot_runtime_host_start (const uint8_t* argv_json, size_t argv_json_len, const uint8_t* env_json, size_t env_json_len) → uint32_t Start the runtime host; argv_json is a JSON array (e.g., ["copilot","--embedded-host"]), env_json is an optional JSON object of environment overrides. Returns a server handle (0 = failure).
    copilot_runtime_host_shutdown (uint32_t server_id) → bool Shut down the runtime host identified by server_id.
    copilot_runtime_connection_open (uint32_t server_id, void(*on_outbound)(void* user_data, const uint8_t* data, size_t len), void* user_data, const uint8_t* ext_source, size_t ext_source_len, const uint8_t* ext_name, size_t ext_name_len, const uint8_t* conn_token, size_t conn_token_len) → uint32_t Open a bidirectional connection on the server; registers the on_outbound callback for runtime→SDK data delivery. ext_source, ext_name, and conn_token are nullable metadata buffers. Returns a connection handle (0 = failure).
    copilot_runtime_connection_write (uint32_t connection_id, const uint8_t* data, size_t len) → bool Write a JSON-RPC frame from the SDK into the runtime. The native side copies the buffer synchronously before returning.
    copilot_runtime_connection_close (uint32_t connection_id) → bool Close a connection.

    The outbound callback signature: void on_outbound(void* user_data, const uint8_t* data, size_t len) — invoked by native code (potentially on native threads) to deliver JSON-RPC responses and notifications back to the SDK.

The cli-native.node addon — a separate, smaller artifact that provides ICU4X text segmentation, Win32 API wrappers, and terminal UI helpers — is a CLI-only artifact used by the Ink/React terminal interface. It is not needed by the Java SDK.

Note on the active Rust migration

As of 2026-07, the runtime.node binary is being built up iteratively as TypeScript runtime code is ported into it. It is not being reduced; it is growing with each port PR. The embedded_host.rs module in the runtime currently spawns a short-lived child process to service method bodies not yet ported to Rust. This internal Node.js dependency shrinks with each port PR and is expected to disappear entirely when the migration completes. The C ABI surface and loading mechanism described in this ADR are stable regardless of migration progress.

Platform dimensions

The runtime must be built for each unique combination of OS, CPU architecture, and (on Linux) C runtime variant. The build system in github/copilot-agent-runtime produces eight Rust target triples:

Platform label Rust triple Constraint
linux-x64 x86_64-unknown-linux-gnu glibc ≥ 2.28 (Debian 10+, Ubuntu 20.04+, RHEL 8+)
linux-arm64 aarch64-unknown-linux-gnu glibc ≥ 2.28
linuxmusl-x64 x86_64-unknown-linux-musl dynamically links musl libc (Alpine Linux)
linuxmusl-arm64 aarch64-unknown-linux-musl dynamically links musl libc
darwin-x64 x86_64-apple-darwin macOS, Intel
darwin-arm64 aarch64-apple-darwin macOS, Apple Silicon
win32-x64 x86_64-pc-windows-msvc MSVC CRT statically linked (+crt-static)
win32-arm64 aarch64-pc-windows-msvc MSVC CRT statically linked (+crt-static)

The GNU/Linux glibc minimum of 2.28 is enforced at build time via a Microsoft/vscode-linux-build-agent sysroot and verified post-build by script/linux/verify-glibc-requirements.sh. The musl binaries are not fully statically linked; they dynamically link musl libc (-C target-feature=-crt-static is explicitly set at build time).

The common case (Windows × 2 + macOS × 2 + GNU/Linux × 2) requires 6 binaries. Supporting Alpine Linux adds 2 more musl binaries for a total of 8.

Platform selection is 100% deterministic

The correct binary can be selected at runtime without any heuristics, using only standard Java and OS APIs:

  1. OS: System.getProperty("os.name") — distinguishes Windows, macOS, and Linux unambiguously.
  2. Architecture: System.getProperty("os.arch") — "amd64" and "x86_64" both map to x64; "aarch64" and "arm64" both map to arm64.
  3. Linux libc variant: Read the first 2 KB of /proc/self/exe and parse the ELF PT_INTERP segment (the dynamic linker path). If the interpreter path contains /ld-musl- → musl; if it contains /ld-linux- → glibc. This requires no subprocess, no PATH lookup, and works inside containers. This is the same approach used by the detect-libc npm package (its primary, most reliable detection method).

Size baseline

Measured from github/copilot-agent-runtime release cli-1.0.69-2 (2026-07-06):

Platform runtime.node (uncompressed) Compressed (~40% deflate)
linux-x64 64.7 MB ~25.9 MB
linux-arm64 55.5 MB ~22.2 MB
linuxmusl-x64 64.4 MB ~25.8 MB
linuxmusl-arm64 55.3 MB ~22.1 MB
darwin-x64 57.3 MB ~22.9 MB
darwin-arm64 48.1 MB ~19.2 MB
win32-x64 55.9 MB ~22.4 MB
win32-arm64 48.4 MB ~19.4 MB

The published Java SDK JAR (copilot-sdk-java-1.0.6-preview.1.jar) is currently 1.53 MB. A monolithic JAR containing all 6 common-case native binaries would be approximately 132 MB compressed; all 8 including musl would be approximately 180 MB compressed.

All native dependencies within the runtime (rustls/aws-lc-rs for TLS, rusqlite with bundled feature for SQLite, zlib-rs for compression) are statically compiled into the binary. There are no dependencies on system OpenSSL, libgit2, or libz.

Considered Options

Option 1: Monolithic JAR — all platform binaries in one artifact

All 6 (or 8) runtime.node binaries are bundled inside the single copilot-sdk-java artifact. At runtime the SDK extracts and loads the one matching the current platform; the remaining 5–7 are carried silently.

Advantages:

  • Single <dependency> in pom.xml; zero extra configuration for users.
  • Familiar pattern: ONNX Runtime (onnxruntime-1.21.0.jar, 130 MB, all platforms) demonstrates this is an accepted norm in the Java ML ecosystem.

Drawbacks:

  • Every user downloads every platform regardless of their target. A developer on Apple Silicon downloads 105+ MB of Linux and Windows binaries they will never use.
  • Build tooling (thin Docker layers, incremental CI caches, artifact registries) penalises large JARs. A single 132–180 MB JAR invalidates the entire cache whenever any platform's binary changes.
  • Maven's dependency resolution has no mechanism to supply platform-appropriate variants automatically; platform selection must happen entirely at runtime inside the JAR.
  • Conflicts with the principle that Maven artifacts should be reproducible and minimal.

Option 2: Per-platform classifier JARs (DJL style)

A small, pure-Java coordination artifact (copilot-sdk-java, ~1.5 MB) is published alongside separate per-platform native artifacts differentiated by Maven classifier:

com.github:copilot-sdk-java-runtime:VERSION:linux-x64
com.github:copilot-sdk-java-runtime:VERSION:linux-arm64
com.github:copilot-sdk-java-runtime:VERSION:linuxmusl-x64
com.github:copilot-sdk-java-runtime:VERSION:linuxmusl-arm64
com.github:copilot-sdk-java-runtime:VERSION:darwin-x64
com.github:copilot-sdk-java-runtime:VERSION:darwin-arm64
com.github:copilot-sdk-java-runtime:VERSION:win32-x64
com.github:copilot-sdk-java-runtime:VERSION:win32-arm64

Each classifier JAR contains only the runtime.node binary for that platform (~19–26 MB compressed) plus a small .properties metadata file. The coordination artifact selects and loads the matching native at startup.

This is the same pattern used by DJL's PyTorch native artifacts (pytorch-native-cpu-2.5.1-linux-x86_64.jar, pytorch-native-cpu-2.5.1-osx-aarch64.jar, etc.), Netty's netty-tcnative-boringssl-static per-platform JARs, and others.

Build tools can be configured to resolve the correct classifier automatically:

  • Maven: <classifier>${os.detected.classifier}</classifier> via os-maven-plugin.
  • Gradle: variant-aware dependency resolution with attribute matching.
  • Uber-jar builds: include all classifiers; the coordination artifact picks the right one at runtime.

Advantages:

  • Default download is the tiny coordination artifact (~1.5 MB) plus one platform JAR (~20–26 MB compressed) — approximately 22–28 MB total vs. 132–180 MB for a monolithic JAR.
  • Each platform JAR changes independently; CI caches and Docker layers for unchanged platforms are preserved across releases.
  • Users building for a single known platform (most production deployments) pay exactly the cost of that platform.
  • Follows well-established Maven ecosystem conventions; standard tooling (os-maven-plugin, Gradle variant resolution) handles classifier selection.
  • Aligns with DJL's proven distribution strategy for large native ML runtimes.

Drawbacks:

  • Requires publishing 6–8 additional Maven artifacts per release.
  • Users building portable über-JARs must explicitly include all classifiers they wish to support.
  • Slightly more complex pom.xml / build.gradle for users who need cross-platform packaging.

Option 3: Download-on-demand (DJL thin placeholder style)

The SDK ships a minimal placeholder that detects the current platform at runtime and downloads the correct runtime.node binary from a distribution endpoint (GitHub Releases or a CDN) on first use, caching it locally (e.g., ~/.copilot/runtime-cache/).

Advantages:

  • Zero native binary content in any published Maven artifact; total download at mvn install is negligible.
  • Identical user experience to the current "externally provided runtime" model during the download, which most CLI users already accept.

Drawbacks:

  • Requires internet access on first run. Offline environments (air-gapped enterprise, CI without outbound HTTP) break silently or require manual pre-seeding.
  • Introduces a network dependency into an otherwise pure library artifact, which violates Maven Central's expectations for reproducible builds.
  • Adds an operational concern: distribution endpoint availability, CDN costs, URL stability across versions.
  • Makes JVM startup non-deterministic in latency (first run downloads 20–26 MB).
  • Cannot be pre-warmed by dependency management tooling; no mvn dependency:resolve analogue works for a runtime download.

Decision Outcome

Chosen: Option 2 — per-platform classifier JARs and Option 1 - monolithic jar. Use maven-assembly-plugin to allow the creation of the monolithic jar.

Rationale

  1. User download cost matches actual need. Most users run on one OS and architecture. Option 2 makes their download approximately 22–28 MB (coordination JAR + one platform JAR), versus 132–180 MB for Option 1 and an unbounded deferred network cost for Option 3.

  2. Proven ecosystem pattern. DJL, Netty, and others have established the per-classifier pattern as the correct Maven idiom for large native binaries. Build tooling already knows how to handle it; users and framework integrations (Spring Boot, Quarkus, Micronaut) are familiar with it.

  3. Cache efficiency. Individual platform JARs change only when that platform's binary changes. Unchanged platform JARs are never re-downloaded or re-cached by CI or developer machines.

  4. No operational dependencies. Unlike Option 3, no external download service is required at runtime. The artifact is self-contained once resolved by Maven/Gradle.

  5. Size per platform is acceptable. At ~20–26 MB compressed per platform, each classifier JAR is well within the range of routinely used native JARs in the Java ecosystem (DJL PyTorch osx-aarch64: 37 MB; ONNX Runtime per platform: ~20–30 MB before bundling).

  6. Option 3 remains composable. A download-on-demand fallback can be layered on top of Option 2 for users who prefer it without changing the primary distribution model. The coordination artifact can attempt classpath lookup first, then fall back to a cached download if no matching classifier JAR is present.

  7. See section How can we do Option 2 and Option 1 for more details.

Binding technology: JNA over Panama FFM

A secondary decision within the scope of this ADR is how the coordination artifact calls the C ABI entry points once the correct runtime.node binary has been loaded. Two candidates were considered: JNA and the Foreign Function & Memory API (FFM, the product of Project Panama, final since Java 22 via JEP 454).

Chosen: JNA. FFM was considered and deliberately deferred, for the following reasons:

  1. Java baseline. The SDK supports Java 17, where FFM does not exist (it finalized in Java 22). A JNA-based binding is therefore required regardless; adopting FFM today would mean maintaining two parallel binding implementations, not replacing one with the other.

  2. Consumer-side configuration burden. FFM downcalls and upcalls are restricted operations under the JDK's integrity-by-default direction (JEP 472). An FFM-based SDK would require every consumer to grant native access explicitly — --enable-native-access=<module> (or ALL-UNNAMED for classpath applications) on the launcher, or an Enable-Native-Access manifest attribute. JNA requires no consumer-side configuration today. For an SDK, this flag becomes every downstream application's problem and a predictable source of support issues. (JNA is on the same enforcement trajectory eventually, as it uses JNI internally; this consideration buys time, not immunity.)

  3. No realizable performance benefit. FFM's principal advantage over JNA is the elimination of per-call reflective marshalling overhead. The C ABI surface here is a fixed set of ~12 entry points carrying JSON-RPC strings; JSON serialization/deserialization cost dominates the call path, and call frequency is bounded by agent-interaction rates rather than tight loops. The latency difference between JNA and FFM is expected to be unmeasurable in end-to-end SDK usage. This calculus would change only if the transport moved to a high-frequency or shared-memory framing model.

  4. Upcall lifetime complexity. The transport is bidirectional: the runtime delivers JSON-RPC responses and server-initiated requests back into Java from native threads. JNA's Callback mechanism handles foreign-thread attachment with well-established semantics. FFM upcall stubs require explicit Arena lifetime management, where a stub whose arena is closed while the Rust side still holds the function pointer results in a JVM crash. This shifts lifetime reasoning that JNA encapsulates onto the binding layer.

  5. GraalVM native-image maturity. JNA's behavior under GraalVM native-image is well established with mature reachability metadata. FFM support in native-image (particularly for upcalls) is newer and varies by GraalVM release. Plausible SDK consumers (e.g., Quarkus/Micronaut-based CLI tools) compile to native images, so this is a compatibility surface the SDK should not destabilize without verification.

  6. FFM's safety advantages do not apply to this ABI shape. FFM's MemorySegment bounds and lifetime checking pays off when Java code performs structural manipulation of native memory. This surface passes strings through a fixed transport; there is little structural memory work to make safe.

Preserving the FFM migration path

FFM is regarded as the likely eventual binding technology: the JEP 472 endgame applies enforcement pressure to JNA as well, and a ~12-function stable C ABI makes a future migration inexpensive. To keep that path open at low cost:

  • The binding layer is abstracted behind a small internal interface (native load + downcall + upcall registration), so that an FFM implementation can be introduced later — for example, as a multi-release JAR selecting FFM on Java 22+ — without changes to the transport or API layers.
  • The decision should be revisited when (a) the SDK's minimum Java baseline moves past 17, or (b) JDK releases begin enforcing --illegal-native-access=deny by default, whichever comes first.

How can we do Option 2 and Option 1

How it works: classpath resource convention + platform detection

1. Each classifier JAR uses a well-known resource path

Each per-platform JAR (copilot-sdk-java-runtime:VERSION:darwin-arm64, etc.) places its binary under a deterministic path inside the JAR:

native/darwin-arm64/runtime.node
native/darwin-arm64/platform.properties

When maven-assembly-plugin creates the uber-jar, it unpacks all dependencies and merges them. The resulting uber-jar contains:

com/github/copilot/sdk/...          (Java classes)
native/linux-x64/runtime.node
native/linux-arm64/runtime.node
native/linuxmusl-x64/runtime.node
native/linuxmusl-arm64/runtime.node
native/darwin-x64/runtime.node
native/darwin-arm64/runtime.node
native/win32-x64/runtime.node
native/win32-arm64/runtime.node

2. The coordination artifact selects at runtime via getResourceAsStream

public class NativeRuntimeLoader {

    public Path loadRuntime() {
        String classifier = detectPlatformClassifier();
        String resourcePath = "native/" + classifier + "/runtime.node";

        try (InputStream in = getClass().getClassLoader()
                .getResourceAsStream(resourcePath)) {
            if (in == null) {
                throw new UnsupportedOperationException(
                    "No native runtime for platform: " + classifier);
            }
            Path cached = getCachePath(classifier);
            if (!Files.exists(cached)) {
                Files.createDirectories(cached.getParent());
                Files.copy(in, cached);
                // Make executable on Unix
                cached.toFile().setExecutable(true);
            }
            return cached;
        }
    }

    private String detectPlatformClassifier() {
        String os = normalizeOs(System.getProperty("os.name"));
        String arch = normalizeArch(System.getProperty("os.arch"));
        String libc = "linux".equals(os) ? detectLinuxLibc() : "";

        // Produces: "linux-x64", "linuxmusl-arm64", "darwin-arm64", "win32-x64", etc.
        return (libc.isEmpty() ? os : os + libc) + "-" + arch;
    }

    private String detectLinuxLibc() {
        // Read ELF PT_INTERP from /proc/self/exe
        // If interpreter contains "/ld-musl-" → "musl"
        // Otherwise → "" (glibc is the default/unmarked case for "linux-")
        // ...
    }

    private Path getCachePath(String classifier) {
        String version = getClass().getPackage().getImplementationVersion();
        return Path.of(System.getProperty("user.home"),
            ".copilot", "runtime-cache", version, classifier, "runtime.node");
    }
}

3. JNA loads from the extracted path

Once extracted to a known filesystem path, JNA loads it directly:

NativeLibrary lib = NativeLibrary.getInstance(extractedPath.toString());
// Or via a mapped interface:
CopilotRuntime runtime = Native.load(extractedPath.toString(), CopilotRuntime.class);

Key insight: the same code works in both modes

The beauty is that getResourceAsStream("native/darwin-arm64/runtime.node") works identically whether:

  • The native lives in a separate classifier JAR on the classpath (normal dev dependency), OR
  • It's been merged into an uber-jar by maven-assembly-plugin

The classloader doesn't care which JAR file the resource came from — it searches the entire classpath. This means zero code changes between the two consumption models.

Assembly plugin configuration (consumer-side)

A consumer building a portable uber-jar would configure:

<plugin>
    <artifactId>maven-assembly-plugin</artifactId>
    <configuration>
        <descriptorRefs>
            <descriptorRef>jar-with-dependencies</descriptorRef>
        </descriptorRefs>
    </configuration>
</plugin>

With all classifier JARs declared as dependencies:

<dependencies>
    <dependency>
        <groupId>com.github</groupId>
        <artifactId>copilot-sdk-java</artifactId>
        <version>${copilot.version}</version>
    </dependency>
    <!-- Include platforms you need -->
    <dependency>
        <groupId>com.github</groupId>
        <artifactId>copilot-sdk-java-runtime</artifactId>
        <version>${copilot.version}</version>
        <classifier>linux-x64</classifier>
    </dependency>
    <dependency>
        <groupId>com.github</groupId>
        <artifactId>copilot-sdk-java-runtime</artifactId>
        <version>${copilot.version}</version>
        <classifier>darwin-arm64</classifier>
    </dependency>
    <!-- ... etc for each target platform -->
</dependencies>

Why this works cleanly

Concern How it's handled
No resource path collisions Each platform has its own subdirectory (native/<classifier>/)
Extraction only happens once Cached to ~/.copilot/runtime-cache/<version>/<classifier>/
Works without uber-jar too Same getResourceAsStream call — classloader finds it in the separate JAR
Subset selection Consumer declares only the classifiers they need; missing platforms get a clear error at runtime
JNA loading NativeLibrary.getInstance(path) loads from an absolute filesystem path after extraction — no JNA platform-detection magic needed

The pattern is identical to how DJL's LibUtils.loadLibrary() works — detect platform, construct resource path, extract if needed, load via absolute path.

Consequences

  • A new Maven module (copilot-sdk-java-runtime or similar) is introduced to hold the per-platform native JARs. The existing copilot-sdk-java coordination artifact depends on it.
  • The coordination artifact gains a platform detection and native loading component that:
    1. Detects OS, architecture, and Linux libc variant deterministically as described above.
    2. Locates the matching runtime.node binary on the classpath (via getResourceAsStream from the classifier JAR).
    3. Extracts the binary to a temporary or cached location (e.g., ~/.copilot/runtime-cache/) if not already present.
    4. Loads it via JNA using the C ABI entry points, per the binding technology decision above. The JNA-specific code is confined behind an internal binding interface to preserve a future FFM migration path.
  • The release pipeline for github/copilot-agent-runtime must produce the per-platform runtime.node binaries as inputs to the Java SDK publish workflow. The per-platform pkg-tarballs-<platform> artifacts from the publish-cli.yml workflow are the authoritative source.
  • Each release of copilot-sdk-java publishes 6 (or 8) classifier JARs to Maven Central alongside the coordination JAR.
  • The version of the bundled runtime.node is recorded in the coordination JAR's manifest and queryable at runtime, enabling diagnostics and mismatch detection.
  • cli-native.node is not bundled. It provides only terminal UI features (ICU4X text segmentation, Win32 APIs, OS desktop notifications) that are irrelevant to the Java SDK's programmatic API surface.

Related work items

References

Term Definition Link
FFI (Foreign Function Interface) A mechanism by which code written in one language can call functions defined in another. In this ADR, Java calls into the Rust runtime shared library via JNA's FFI layer. https://en.wikipedia.org/wiki/Foreign_function_interface
JNA (Java Native Access) A Java library that provides easy access to native shared libraries without requiring the JNI boilerplate. Used here to call the extern "C" C ABI entry points exported by runtime.node. https://github.com/java-native-access/jna
napi-rs A Rust framework for building native Node.js addons using the Node-API (napi) stable ABI. Produces the .node file and generates TypeScript type declarations automatically. https://napi.rs/
cdylib A Rust crate-type that produces a C-compatible dynamic shared library (.so / .dylib / .dll). Distinct from dylib (Rust-to-Rust only) and staticlib. https://doc.rust-lang.org/reference/linkage.html
napi (Node-API) A stable C ABI provided by Node.js for building native addons that remain binary-compatible across Node.js versions. napi-rs generates Rust code against this interface. https://nodejs.org/api/n-api.html
C ABI (Application Binary Interface) The low-level contract between a compiled binary and its callers: calling conventions, data type layouts, symbol naming. An extern "C" ABI uses C's conventions, making a library callable from any language that speaks C FFI. https://en.wikipedia.org/wiki/Application_binary_interface
ELF PT_INTERP A segment in an ELF binary (the Linux/Unix executable format) that records the path of the dynamic linker/interpreter. On glibc systems this path is /lib64/ld-linux-x86-64.so.2; on musl systems it is /lib/ld-musl-x86_64.so.1. Inspecting it is the most reliable way to detect glibc vs. musl at runtime without executing a subprocess. https://man7.org/linux/man-pages/man5/elf.5.html
glibc (GNU C Library) The standard C runtime library on most mainstream Linux distributions (Debian, Ubuntu, RHEL, Fedora, SLES). Binaries linked against glibc require the same version or newer to be present at runtime. The runtime.node glibc build requires glibc ≥ 2.28. https://www.gnu.org/software/libc/
musl libc An alternative C standard library optimised for static linking and used as the default libc on Alpine Linux. Not binary-compatible with glibc; a separate runtime.node build is required. https://musl.libc.org/
MSVC CRT (Microsoft Visual C++ Runtime) The C runtime library shipped with Visual Studio. When compiled with +crt-static (as runtime.node is on Windows), it is statically linked into the binary and the end-user does not need to install the Visual C++ Redistributable. https://learn.microsoft.com/en-us/cpp/c-runtime-library/c-run-time-library-reference
Project Panama The OpenJDK project that produced the Foreign Function & Memory API as the modern, supported replacement for JNI-based native interop. https://openjdk.org/projects/panama/
FFM (Foreign Function & Memory API) The java.lang.foreign API for calling native functions and managing native memory from Java, finalized in Java 22. Considered and deferred as the binding technology for this SDK; see Binding technology. https://docs.oracle.com/en/java/javase/22/core/foreign-function-and-memory-api.html
JEP 454 The JDK Enhancement Proposal that finalized the FFM API in Java 22. https://openjdk.org/jeps/454
JEP 472 "Prepare to Restrict the Use of JNI" — part of the JDK's integrity-by-default direction under which native access (via JNI or FFM) requires explicit consumer opt-in (--enable-native-access). Drives both the FFM configuration-burden concern and the expectation that JNA itself will eventually require the same opt-in. https://openjdk.org/jeps/472
DJL (Deep Java Library) Amazon's open-source Java framework for ML inference, used here as a reference for the per-platform classifier JAR distribution pattern. Its PyTorch native artifacts (pytorch-native-cpu-*-<platform>.jar) are the direct model for the proposed copilot-sdk-java-runtime:VERSION:<classifier> artifacts. https://djl.ai/
os-maven-plugin A Maven extension that detects the current OS and architecture and exposes them as properties (e.g., ${os.detected.classifier}) so that <classifier> values can be resolved at build time rather than hardcoded. https://github.com/trustin/os-maven-plugin
ONNX Runtime Microsoft's cross-platform ML inference runtime, used in this ADR as the size comparable for a monolithic all-platform JAR (~130 MB, Option 1). https://onnxruntime.ai/

Additional source references: