Cross-Language Bindings and Boundary Architecture

A legacy image-analysis engine must call wireview from four places: a C++ desktop process with a 40-microsecond per-record budget, a Python notebook that values array ergonomics, a JVM service whose workers are restarted independently, and a browser client that receives untrusted files. “Generate bindings” is not one architecture. These callers disagree about ownership, thread attachment, garbage collection, exception behavior, deployment, and acceptable failure radius.

The decision record starts with consequences rather than language preference:

The controlling rule is simple: a binding must translate the foreign runtime’s contracts into a smaller Rust boundary without inventing ownership or concurrency guarantees that neither side can enforce. The stable C ABI from the previous unit is often a useful lowest common denominator. It is not the whole integration architecture and it is not automatically the best public interface.

Design the boundary stack, not a pile of wrappers

A production binding has at least four layers:

1. a Rust kernel with safe types and explicit invariants;
2. a narrow native or wire boundary with stable representation and failure rules;
3. a runtime adapter that owns foreign handles, thread checks, and error translation;
4. an idiomatic language API that follows local naming, lifetime, async, and packaging expectations.

Collapse these layers and responsibilities become ambiguous. If generated Python declarations call raw wireview_free, ordinary Python code can double-release a handle. If C++ templates reach directly into Rust layout, an internal Rust refactor becomes an ABI break. If a Java object stores a native address but finalization is the only release path, native memory pressure becomes invisible to the garbage collector. If every JavaScript record crosses the host boundary individually, a theoretically zero-copy parser can lose to call overhead.

The diagram is a review map, not a prescription that every adapter must use C. A Rust-to-C++ bridge can generate a typed, mutually understood surface. A Wasm export uses the module’s linear-memory and host-call model rather than the machine’s native C ABI. IPC replaces addresses with a protocol. The durable move is to keep the Rust kernel independent of whichever adapter is selected.

Generated bindings remove transcription work. They do not generate the semantic contract. A header parser can reproduce parameter widths and names while remaining silent about whether a pointer is borrowed, retained, nullable, thread-confined, or released by the caller. A code generator is safest when it consumes authoritative metadata containing those facts and emits a thin mechanical layer. Handwritten adapter code then enforces the runtime-specific policy.

Treat generated output as a build artifact with provenance: pin the generator, record its command and target triple, review diffs, compile against the real library, and test the installed package. Decide whether generated files are checked in. Checking them in improves review and downstream builds that lack the generator; generating them at build time reduces stale files but adds hermeticity and bootstrap obligations. Either policy needs one source of truth and a drift check.

One matrix exposes the hidden contracts

Before choosing tooling, complete an ownership and thread-affinity matrix for every exposed type:

“Garbage collected” is not an ownership policy. It explains when managed references become unreachable, not when a native object must be released. “Runs on the main thread” is not a thread policy unless the adapter identifies which main thread, how callbacks arrive there, and what happens during shutdown. “Zero copy” is not a lifetime policy. It is an optimization that requires one owner to remain alive and immobile while another runtime holds a view.

A wrapper should establish one native ownership token per foreign object. Closing consumes that token at the wrapper layer and changes the wrapper to a closed state before invoking native release. A finalizer or cleaner is a leak backstop, not the primary protocol: its timing can be nondeterministic, it may run on a special thread, and the process can end without it. Expose deterministic close, context-manager, try/finally, or RAII forms idiomatic to the host.

If native memory materially exceeds the managed wrapper’s size, account it to the runtime where supported or cap it in the adapter. Otherwise the garbage collector sees a tiny object while Rust owns gigabytes, so collection arrives too late. Observability should report live native handles, owned bytes, queued callbacks, and releases by reason: explicit, scope cleanup, finalizer backstop, or process exit.

C++: typed bridges and two exception systems

C++ can consume the C ABI directly behind an RAII class:

class parser {
public:
    parser();
    ~parser() noexcept;
    parser(parser&&) noexcept;
    parser& operator=(parser&&) noexcept;
    parser(const parser&) = delete;
    std::uint32_t parse(std::span<const std::byte> input);
private:
    wireview_handle* raw_ = nullptr;
};

The class makes one owner movable but not copyable, calls wireview_free exactly once, converts a span to pointer and length for one call, and converts status to a C++ error form. Its destructor must not throw. Move assignment must release or transfer the previous token without leaks. A moved-from object remains destructible and rejects use.

A typed bridge generator can expose strings, vectors, unique ownership, and selected Rust/C++ types more directly than a C surface. That can improve safety and eliminate manual declarations, but it couples both builds to the bridge’s supported type set, code generation, compiler/toolchain matrix, and runtime support. Keep the exported vocabulary small. Do not mirror an entire Rust domain graph merely because the generator accepts it.

Exception translation must stop at native frames. Catch C++ exceptions in a C++ shim before returning to Rust. Catch or abort Rust panics according to the exported ABI policy before returning to C++. Then translate a stable error record into std::error_code, an expected-like result, or a documented exception at the idiomatic C++ layer. Throwing is a C++ API choice; it does not authorize an exception to unwind through Rust.

Callbacks need the same discipline. A captured C++ callable usually requires a heap-owned trampoline context. Registration owns or shares that context; unregister prevents new calls; a drain/join phase waits for in-flight calls; only then can deletion occur. If Rust invokes on worker threads, the C++ contract must say so. Never assume thread-local state, GUI affinity, or exception handlers from the registration thread will exist on the callback thread.

Python: object lifetime, buffers, and interpreter state

An idiomatic Python extension should expose a Parser object, not an integer address. Construction creates the Rust handle. close() marks the object closed and releases it. __enter__/__exit__ provide deterministic scope; deallocation is a backstop. Every method checks the closed flag before reaching native code.

Bulk bytes can arrive through Python’s buffer protocol or an extension framework’s byte/slice types. Borrow them only for the call unless the returned object explicitly keeps the exporting Python owner alive. If Rust releases the interpreter lock around parsing, it must not access Python objects, invoke Python callbacks, or rely on the input remaining immutable unless the buffer contract guarantees those properties. Copying into Rust-owned storage is sometimes the correct repair, especially for mutable exporters or asynchronous work.

Python runtimes have rules about interpreter attachment and global/interpreter locks; those rules and APIs evolve and can differ between interpreter builds. Bind against a supported runtime matrix and use the binding framework’s current attachment primitives. Do not state “the GIL protects it” as a Rust synchronization proof. A Rust object shared across extension calls still needs valid Rust Send/Sync reasoning, and releasing a runtime lock can expose real concurrency.

Translate WireviewStatus into a small exception hierarchy at the outer adapter. Invalid input can become ValueError or a library-specific parse exception; resource exhaustion should retain a distinct category; internal panic containment should become a generic native-library failure without exposing a panic payload. Preserve structured fields such as byte offset separately from the human message. Never leave a Python-visible result partially initialized when translation raises.

Async integration rarely means calling a synchronous native function directly in an event-loop callback. Short CPU work may be acceptable within a measured budget; long or blocking work belongs in an executor or native async integration that reports completion back through the runtime’s supported scheduler. Cancellation of the Python awaitable does not automatically stop Rust work. Specify whether cancellation requests cooperation, merely abandons the result, or waits for native cleanup.

JVM and .NET: handles, pinning, and attached threads

JNI and .NET interop commonly represent a native token as a machine-sized integer inside a managed object. That representation is convenient but unsafe by default: arbitrary values can be forged, closed objects can be reused, and a racing close can invalidate a handle during a call. Keep the field private, validate state in native entry points, and synchronize acquisition with close. For larger systems, an adapter-owned handle table with generation counters can reject stale tokens more reliably than exposing addresses.

Managed arrays and strings are not Rust slices. A runtime may copy, pin, or expose elements under constraints. Pinning can inhibit garbage-collector movement and should be brief; copying has bandwidth and allocation costs but simplifies lifetime. Critical access APIs may prohibit blocking or arbitrary runtime calls. Choose per operation and measure with realistic payloads. For long asynchronous operations, copy into native ownership or use a runtime-supported direct/native buffer whose cleanup is explicit.

Callbacks from Rust-created threads must attach to the managed runtime according to its API and detach when required. A native thread generally cannot fabricate a Java object reference or call a managed delegate merely because it has a function pointer. References retained beyond one call often need global/rooted forms, then explicit unrooting after callbacks drain. Thread-local exceptions are detected and translated on the attached thread; they must not cross native frames.

For .NET, a safe-handle-style wrapper can coordinate deterministic release and finalization more reliably than a raw IntPtr. Delegates passed to native code must remain rooted for as long as callbacks are possible. For JVM code, AutoCloseable and try-with-resources make native lifetime visible. In both environments, record the native library version and target variant actually loaded; package resolution errors often masquerade as API failures.

Async methods should complete a managed future/task through the runtime’s scheduling mechanism. Decide how native cancellation tokens map to managed cancellation, where completion callbacks run, and whether close waits for work. A future becoming unreachable is not a cancellation protocol. A timeout returning to managed code is not proof the native operation stopped.

JavaScript and Wasm: linear memory changes the meaning of a pointer

In a Wasm module, an exported pointer is normally an offset into the module’s linear memory, not a host address. JavaScript must copy input into that memory unless a host integration provides a shared view under explicit rules. If memory grows, previous typed-array views can become detached or stale depending on the environment. Hide allocation and growth behind a wrapper and recreate views when required.

Crossing the JavaScript/Wasm call boundary per field can dominate parsing. Prefer coarse operations: copy or expose one record batch, parse many records in Wasm, and return compact results. Budget four quantities separately: host-to-module bytes, module-to-host bytes, allocation count, and host-call count. “Wasm is zero copy” is false as a general claim; even when a typed array views linear memory, the input may already have been copied into it.

JavaScript errors and promise rejections should carry stable codes, not only formatted strings. Rust panics may be mapped by the toolchain glue, but an application should define whether they reject an operation, poison an instance, or terminate a worker. Browser and server-side JavaScript differ in threads, filesystem access, module formats, and packaging; test each supported host.

Wasm can provide a useful sandbox boundary, but it is not identical to an operating-system process. Capability exposure, memory limits, host imports, denial-of-service controls, and engine vulnerabilities remain part of the threat model. If wireview handles hostile files, cap linear memory and input work, fuzz the Wasm export path, and consider moving high-risk parsing into a worker or remote process.

Async interop needs one cancellation owner

Every runtime has a type that resembles a future, promise, task, or callback, but resemblance does not create shared semantics. An adapter specification must name:

• who owns the in-flight Rust operation;
• what keeps foreign state alive;
• which thread/executor polls or completes it;
• how results cross back;
• what foreign cancellation requests;
• which cleanup is guaranteed before completion;
• what close does while work is active;
• how panic, exception, disconnect, and runtime shutdown appear.

One robust pattern allocates an operation record owned by Rust, roots the minimal foreign completion handle in the adapter, and returns a foreign future. Cancellation flips a Rust-visible token. Completion schedules a small adapter closure onto the foreign runtime, resolves or rejects exactly once, releases the root, and destroys the operation. Close first prevents new work, requests cancellation, then drains or explicitly detaches according to policy.

Avoid two independent owners racing to free the operation. Foreign cancellation and Rust completion should contend on one state machine: pending → completing → completed, with pending → cancelling → completed as the competing path. Losing transitions observe completion rather than release resources again.

Make the data-copy budget numerical

Cross-language performance reviews often count copies vaguely while ignoring calls, allocation, pin duration, and cache effects. Write a budget per request:

copied_bytes = input_copy + output_copy + framing_copy
boundary_calls = setup + batches + completion
pinned_byte_micros = pinned_bytes × pin_duration
owned_native_bytes = handles + queued_work + retained_buffers

The lab’s BoundaryPlan makes one deliberately simple choice executable. Mutual distrust or independent restart forces a process boundary even when latency prefers in-process calls. Otherwise a sub-100-microsecond budget chooses an in-process adapter. IPC’s modeled copy budget is two payload copies per boundary call. The policy is not universal; its value is that reviewers can challenge thresholds and assumptions in code rather than accept “FFI is faster.”

Batching may reduce call overhead while increasing latency and retained memory. Borrowing may remove a copy while extending pin or owner lifetime. Shared memory may remove payload copies while introducing synchronization, lifetime, validation, and stale-reader protocols. Serialization costs CPU and bytes but creates a stable, inspectable message boundary. Measure the complete adapter, including language object construction and packaging mode, not only the Rust kernel.

Packaging is part of correctness

An integration can pass source tests and fail because the wrong binary loads. Define the package matrix: operating system, architecture, runtime version/ABI, C runtime, minimum OS, debug-symbol policy, dynamic/static linkage, and CPU feature baseline. Python wheels, JVM native resources, .NET runtime identifiers, Node/Wasm packages, and C++ package managers each have different selection and signing conventions.

Keep the native library, generated declarations, adapter code, licenses, and version manifest from one build. On startup, query and log the ABI version. Fail closed on incompatible versions rather than attempting a call. Test installation into a clean environment without compiler or source tree. Check loader search paths so an older system copy cannot shadow the packaged artifact.

ABI stability protects binary calling compatibility for a stated target. API stability protects source-level names and behavior for users of the idiomatic wrapper. Protocol stability protects independently deployed peers. These promises can move separately. A Python wrapper can make an API-breaking rename while its C ABI stays unchanged; a C++ template implementation can require recompilation without changing behavior; an IPC server can retain its wire protocol while replacing every native symbol.

Version the layer consumers actually depend on. Test old wrapper/new native library and new wrapper/old native library only when that combination is promised. Avoid interpreting an ABI version as a capability set; provide explicit feature discovery where optional operations exist.

Test conformance at each seam

A binding test suite should fail at the layer that owns the defect. Rust kernel tests establish parsing and state invariants. ABI tests compile the declarations, inspect symbols, and exercise allocation, error, callback, and release protocols. Adapter tests work through the C++, Python, managed, or JavaScript public object. Package tests install the produced artifact in a clean runtime and confirm that the intended library was loaded. End-to-end tests cover only a few high-value compositions; making every semantic case cross every language produces a slow suite with poor fault localization.

Build a contract matrix rather than copying one happy-path test:

Negative lifetime tests need care. Deliberately dereferencing a stale native token in the ordinary test process invokes undefined behavior and can corrupt unrelated assertions. Test wrapper-level rejection deterministically. Put hostile native misuse in subprocesses under sanitizers or other containment, and classify whether the native contract promises rejection at all. A C ABI cannot cheaply validate every forged address.

Test callback teardown as a temporal protocol, not two independent methods. Arrange one callback to block after entering, call unregister or close from another thread, verify that new callbacks stop, release the blocked callback, and verify that drain completes before userdata is destroyed. Repeat under concurrency instrumentation where supported. If the API instead documents that close fails with busy, assert that behavior and require the caller to drain explicitly.

Use failure injection to reach paths that production rarely exercises: allocation rejection, scheduler refusal, runtime-detach during completion, loader mismatch, child-process crash, truncated IPC response, and adapter exception construction failure. Injection hooks should be test-only or capability-scoped; a global “fail next allocation” switch can create cross-test races and misleading coverage.

Conformance tests must assert more than “no crash.” Check exact status mapping, unchanged outputs on failure, one release, callback thread identity, bounded retained bytes, no completion after close, loaded ABI version, and diagnostic redaction. Collect native handle and byte gauges before and after stress loops. A stable count after quiescence is stronger leak evidence than waiting for an unspecified finalizer.

Generated layers need structural checks. Compare the exported symbol allowlist, generated declaration hash, ABI version, and package manifest. Compile public headers as both C and C++ when promised. For managed bindings, reflect over method signatures and platform metadata. For Wasm, inspect imports/exports and enforce memory limits. These checks catch drift before execution reaches an incorrectly declared function.

Cross-language continuous integration can become combinatorial. Define a small required axis set: Rust snapshot and MSRV where the native crate claims both, supported operating-system/architecture pairs, oldest and newest supported host runtime, debug/release or panic profiles that alter behavior, and compatibility pairs actually promised. Run the fast semantic core broadly; run expensive stress and sanitizer jobs on representative targets; rotate secondary target stress on a schedule. A skipped required runner is missing evidence, not a green result.

Repairs that compile but weaken the architecture

Several convenient repairs erase rather than satisfy a boundary contract.

Copying every buffer fixes many lifetime mistakes but can violate latency and memory budgets, especially when adapters copy once into native memory and again into language objects. Make the copy visible and measure it. If the budget cannot afford it, redesign ownership or batch shape rather than labeling the copy temporary.

Leaking a callback context avoids use after free while creating unbounded native retention. Holding a global runtime lock around every Rust call may serialize races while causing deadlocks, blocking unrelated code, and making callbacks reentrant under the same lock. Wrapping a raw handle in an atomic integer prevents torn reads but does not coordinate close with an in-flight operation. Catching every exception and returning “internal error” contains unwinding but destroys actionable categories and may hide that the handle is poisoned.

Making a handle reference-counted on both sides can create two independent ownership systems. The foreign runtime may believe its object is closed while native callbacks keep the Rust allocation alive, or Rust may release its count while a managed delegate remains reachable. If shared lifetime is required, specify who creates and drops each strong reference, how cycles are broken, and when logical close differs from physical destruction.

Using a process boundary is not a universal escape. It converts memory-safety coupling into protocol, availability, and operational coupling. An unbounded request queue can move an in-process memory leak into a service. Automatic retries can duplicate effects. Shared memory can recreate pointer-like lifetime and synchronization hazards across processes. The architecture improves only when the protocol adds explicit bounds, identities, ownership, and failure recovery.

A final weak repair is narrowing the support statement only in prose after shipping broad packages. If the adapter is tested only on one target/runtime, package metadata, installation guards, and documentation should agree. Otherwise users discover the real matrix through crashes. Expand support by adding evidence, not by assuming adjacent runtime versions behave alike.

When a process boundary is the better abstraction

Use in-process FFI when latency and copy budgets dominate, both components share deployment and trust, crash fate can be shared, target combinations are controlled, and runtime attachment rules are manageable. Its benefits are direct calls, borrowed memory, fewer serialization steps, and simpler synchronous flow. Its cost is one address space: memory corruption, abort, loader conflict, thread misuse, and resource exhaustion can take down the caller.

Prefer IPC when components require independent restart or rollout, inputs or plugins are mutually untrusted, runtimes have conflicting dependencies, ABI matrices are too expensive, resource limits need enforcement, or failure containment matters more than microseconds. A versioned protocol makes ownership explicit because messages are values rather than borrowed addresses. It also introduces serialization, scheduling, backpressure, authentication, partial failure, and distributed lifecycle.

Do not move across a process boundary while preserving a chatty object API. Replace fine-grained calls with coarse operations and batches. Add deadlines, bounded queues, request IDs, idempotency where retries are allowed, and explicit overload responses. The process boundary is an architectural redesign, not a transport switch.

Architecture exercise: decide the legacy integration

You own a proprietary C++ host with a plugin ABI, embedded Python for automation, and a JVM control plane. Files are untrusted, median records are 8 KiB, some are 64 MiB, the C++ render loop permits 50 microseconds per small record, and the control plane can tolerate 20 milliseconds. Plugins crash often and must be rolled independently. Produce:

1. a boundary map showing which calls remain in process and which cross IPC;
2. the ownership/thread/failure matrix for buffers, parser handles, callbacks, and asynchronous operations;
3. a numerical copy, call, pin-duration, and retained-native-memory budget for small and large files;
4. exception/panic translation paths for C++, Python, JVM, and the service protocol;
5. a shutdown trace covering callback drain, cancellation, native handle release, and child-process termination;
6. a packaging/compatibility matrix with clean-install and old/new tests;
7. a decision record listing rejected alternatives and residual risks.

A defensible design likely keeps a measured synchronous path in the trusted C++ host, exposes a scoped Python adapter for automation, and routes untrusted plugin/control-plane work through a coarse, bounded process service. That is not the only acceptable answer. A design can keep everything in process if it demonstrates that crash fate, trust, packaging, and runtime attachment are acceptable; it can move everything out of process if it meets the render budget through batching, caching, or shared memory with a complete synchronization protocol.

Review the proposal with these questions:

• Does every foreign object correspond to exactly one native ownership token?
• Are close, finalizer, callback drain, and runtime shutdown ordered?
• Are runtime locks and thread attachment treated as runtime rules, not Rust synchronization?
• Can any exception, panic, or non-local exit cross an unsupported native frame?
• Does every borrowed or pinned buffer name its owner and maximum duration?
• Are async completion and cancellation one state machine with one release point?
• Is the copy budget measured at the idiomatic API, including object conversion?
• Can the packaged adapter prove which native binary it loaded?
• Are ABI, source API, and wire-protocol compatibility promises separated?
• Would a crash, compromised plugin, or dependency conflict justify IPC?

The result of this review is a boundary architecture, not merely generated code. Each adapter should be thin enough that its ownership and thread rules are auditable, yet idiomatic enough that ordinary foreign callers never manipulate raw tokens.

The next task is to test the unsafe kernel and all these adapters without overreading the result. A clean unit suite cannot establish that raw-pointer preconditions are complete; a fuzzer cannot explore every allocation and schedule; a sanitizer cannot validate an unsupported target. Confidence has to accumulate from review, interpreters, instrumentation, generated inputs, differential oracles, integration tests, and disciplined change control.

Sources and version notes

The executable policy fixture targets Rust 2024, declares Rust 1.85 as its MSRV, and is checked with the book snapshot Rust 1.97. Runtime-specific APIs, packaging tags, bridge generators, interpreter-lock models, and Wasm hosts are version-sensitive third-party or platform behavior and must be pinned for an implementation. Durable primary references include the Rust Reference on external blocks and type layout, standard documentation for CStr, Python’s current C API guidance for thread state and the buffer protocol, the JVM specification’s native-thread attachment rules, and the WebAssembly core specification. Binding-framework documentation is authoritative only for the pinned framework/runtime combination; it does not replace the ownership and failure contract recorded here.