Companion language bindings (C++ and C#) #

wolfram's core SDK must remain pure C23. The C23 core (libwolfram) is the single source of truth: it owns transport, crypto, DAG-CBOR, DNS, and the server. Companion languages are consumer layers that link libwolfram and call into it — they must never re-implement signing, hashing, serialization, transport, or server logic.

This document records the agreed conventions for the two C-adjacent bindings: C++ (wolfram-cpp) and C# (Wolfram.Interop).

Hard constraints (apply to every binding) #

1. Wrappers only — never reimplement. The C++ and C# layers are thin pass-through wrappers over libwolfram. They must not reimplement any wolfram logic: no signing/hashing (libsecp256k1/OpenSSL), no DAG-CBOR or CAR (libcbor), no transport/DNS (libcurl/c-ares), no server (libmicrohttpd). Every wrapper ultimately calls a libwolfram function; the binding layer only adds ownership (RAII/SafeHandle), error mapping, and idiomatic naming. If wolfram has an honest stub (WF_ERR_INVALID_ARG + TODO), the binding surfaces that as an error/exception — never a fabricated success.
2. Ownership mirrored 1:1. wolfram exposes a uniform contract: every owned output type wf_T has a matching wf_T_free, and JSON strings use wf_*_json_free(char*) (freed via cJSON_free, not free/delete). Each binding wraps these with its native ownership primitive.
3. Status handling. The wf_status enum (_result.h: WF_OK = 0, WF_ERR_INVALID_ARG, WF_ERR_ALLOC, WF_ERR_NETWORK, …) maps to the language's native error model; WF_OK is success.
4. Encoding is UTF-8. All char* strings are UTF-8. Marshalling must be explicit; do not rely on platform defaults (UTF-16 in .NET/JS).
5. Optional modules are feature-gated. WOLFRAM_BUILD_SERVER, WOLFRAM_BUILD_STORE, WOLFRAM_BUILD_STORE_CRYPTO change which symbols exist in libwolfram; bindings gate those surfaces accordingly.
6. Public headers are extern "C". Both languages consume the existing include/wolfram/*.h directly (C++ includes them; C# parses them with ClangSharp). No hand-maintained signature duplication where a generator fits.

C++ — wolfram-cpp (header-only RAII layer) #

Implemented as cpp/wolfram-cpp/ (build with -DWOLFRAM_BUILD_CPP=ON; the wolfram-cpp-smoke test exercises it offline). C++ includes the C headers directly, so there is no binding generator for the wrapper itself — just a thin RAII layer:

• wolfram/unique_handle.hpp — unique_handle<T, Free> RAII owner mirroring wolfram's wf_T + wf_T_free contract (move-only, get()/release()/reset()).
• wolfram/cstring.hpp — RAII owner of a heap char*; default deleter is std::free, pass a wf_*_json_free for cJSON-backed strings.
• wolfram/status.hpp — wf_status → std::error_code via a custom error_category, plus wolfram::require(wf_status) that throws std::system_error. wf_status is is_error_code_enum-enabled so it constructs std::error_code directly.
• tools/gen_owners.cpp — scans include/wolfram/*.h for void wf_<T>_free(...) and emits wolfram/generated_owners.hpp with one wf_<T>_handle typedef per owned type (372 handles from 51 headers). Regenerate after changing headers.
• wolfram/wolfram.hpp — umbrella include.

Core changes required for C++ consumption #

The C public headers were made C++-clean as part of adding this wrapper:

• Unified the two status enums: wf_status (xrpc.h) is now the single canonical enum (full 27-code set, values preserved from the old wf_error); wf_error (in _result.h) is a typedef alias of wf_status. Previously the same enumerators existed in both enums with divergent values (e.g. WF_ERR_RATE_LIMIT was 8 vs 21), which broke any translation unit that included both.
• _result.h now wraps its declarations in extern "C" and no longer has a stray type token before static inline (a latent bug that also failed to compile in C++).
• project(... LANGUAGES C CXX) so the C++ target is buildable.

C# — Wolfram.Interop (P/Invoke, AOT-capable) #

Implemented as dotnet/Wolfram.Interop/ (build + test with dotnet test dotnet/Wolfram.Interop.Tests). Pure pass-through wrappers — no crypto, transport, DAG-CBOR, or server logic is reimplemented; every call forwards to libwolfram.

• Raw tier (Internal/Raw.cs) — LibraryImport (source-generated, NativeAOT/trim-safe) P/Invoke declarations, 1:1 with the C ABI. UTF-8 strings explicit (StringMarshalling = Utf8 / UnmanagedType.LPUTF8Str), nuint for size_t, opaque handles as IntPtr. A combined DllImportResolver loads libwolfram (honoring WOLFRAM_NATIVE_LIB) and the platform libc (only to free owned strings the SDK returns).
• Managed tier — XrpcClientHandle : SafeHandle owns wf_xrpc_client* (released via wf_xrpc_client_free; no raw IntPtr escapes). Status mirrors wf_status; WolframException is raised on non-Ok (honest stubs surface here, never faked). Wolfram / WolframClient give an idiomatic API.
• Regeneration — tools/generate.rsp is a ClangSharpPInvokeGenerator response file to regenerate/expand the raw tier from include/wolfram/*.h (the hand-written Raw.cs currently covers the wrapped functions).

Layout #

• cpp/wolfram-cpp/ — header-only C++ RAII wrapper (links libwolfram).
• dotnet/Wolfram.Interop/ — raw P/Invoke tier + hand-written managed layer (links libwolfram).

Both consume the same built libwolfram; neither ships crypto/transport code.