# ADR 0006: One binding technology per language

Documentation version: 0.3.1.

**Status:** accepted · **Date:** 2026-10-20

## Context

ADR 0005 fixes *what* the SDKs expose. This record fixes *how* each one
reaches the Rust core, choosing in each language the most widely adopted
native-binding technology that needs no extra runtime, so that the thin
layer stays thin and the packages install the way that language's users
expect.

Two routes exist: a native extension built from the Rust crates (the
host's own extension API, one build per platform and runtime) or a call
into the C ABI (one shared library per platform, loaded by the language's
foreign-function facility). The first gives the most idiomatic packages
where mature tooling exists; the second keeps the binding to a few hundred
lines and needs no compiler on the user's machine.

## Decision

| Language | Technology | Package | Why |
|----------|------------|---------|-----|
| Rust | the `sourceorrery` crate, directly over `sourceorrery-storage` | crates.io `sourceorrery` | It *is* the client every other binding wraps. |
| Python | PyO3 + maturin, abi3 wheels for 3.11+ | PyPI `sourceorrery` | The de facto standard for Rust extensions; one wheel per platform for every Python version; maturin builds, tests and publishes. |
| JavaScript / TypeScript | napi-rs 3 with the generated loader and hand-written types for the public wrapper | npm `@sourceorreryai/sdk` plus one package per platform (`@sourceorreryai/sdk-<platform>`) as optional dependencies | Node-API gives ABI stability across Node versions; napi-rs is the standard Rust toolkit for it and handles the per-platform package layout. |
| Java | Foreign Function and Memory API (`java.lang.foreign`, final in Java 22) over the C ABI | Maven Central `ai.sourceorrery:sourceorrery` | Part of the JDK; no JNI glue, no second native library to build. JNA would add a runtime dependency; JNI would add C to maintain. The jar embeds the shared library per platform. |
| .NET | `LibraryImport` source-generated P/Invoke (.NET 8+) over the C ABI | NuGet `SourceOrrery` with `runtimes/<rid>/native` | Trimming- and AOT-safe, no runtime marshalling, the layout NuGet already understands. |
| Go | cgo over the C ABI, header vendored in the module | pkg.go.dev `github.com/netizine/sourceorrery/bindings/go` | The one supported way to call C from Go; the module needs only the shared library on the linker path. |
| C | the cbindgen header itself | the `sourceorrery-ffi-<version>-<target>` release archive | Nothing to add. |
| C++ | a header-only C++17 RAII wrapper over the C header | the same archive (`sourceorrery.hpp`) | No build system to adopt; RAII gives zeroise-on-scope-exit for free. |
| PHP | the built-in FFI extension (PHP 8.2+) over a vendored subset of the C declarations | Packagist `sourceorrery/sourceorrery` | Bundled with PHP; no extension to compile or load. |

Common rules:

* Metadata crosses as the core's JSON shape; values cross as bytes.
  Bindings parse JSON with the language's own facility (a dependency-free
  reader where the standard library has none: Java and C++).
* Thread-local error state (`so_last_error_*`) is read on the thread that
  made the call: Go pins its OS thread for each call; Java reads the state
  immediately with no blocking operation in between; the others are
  single-threaded per call by construction.
* The native extension crates (Python, Node) live outside the Cargo
  workspace, as their own workspace roots with their own lock files, so
  `cargo test --workspace` never needs a Python or Node toolchain and the
  packaging tools build them with the features they need.
* Native libraries ship inside the packages where the ecosystem supports
  it (npm platform packages, NuGet `runtimes/`, the jar) and from the
  GitHub Release archives otherwise (Go, C, C++, PHP), always built by the
  same release workflow from the same commit.

## Consequences

* Adding a platform means adding it to the native build matrix once; every
  C-ABI binding picks it up from the archive, Python and Node need a
  matrix entry each.
* The Rust crates stay the compatibility contract (`CONTRACT_VERSION`);
  generator versions can change without changing the meaning of a call.
* Java requires Java 22 or newer and `--enable-native-access`; PHP
  requires the FFI extension enabled for the CLI SAPI (the default); Go
  users need a C toolchain. The per-language pages state these up front.
