Module ffi 

C ABI for the JSON command bridge — the entire mobile-facing surface.

Three symbols. Ownership rules (also documented in the shipped header):

• The caller owns the input buffer; the engine never retains it past the call.
• Every pointer returned by ballistics_bridge_call / ballistics_bridge_call_n is heap-allocated by the engine and must be released exactly once with ballistics_bridge_free. Freeing NULL is a no-op.
• The calls NEVER return NULL: every failure mode — invalid UTF-8, bad JSON, unknown command, command failure, internal panic — is an in-band {"ok":false,...} envelope.
• Calls are independent and thread-safe; there is no shared mutable state.

Android callers want ballistics_bridge_call_n over a ByteArray, not ballistics_bridge_call over a jstring: JNI’s string conversions speak modified UTF-8, which call_with_bytes below refuses. docs/ANDROID_JNI_BRIDGE.md has the worked example and the reasoning; tests::a_request_in_jni_modified_utf8_is_refused pins the behaviour it argues from.

Functions

ballistics_bridge_call^⚠

Process one bridge request (NUL-terminated UTF-8 JSON envelope).

ballistics_bridge_call_n^⚠

Length-explicit variant for callers whose buffers are not NUL-terminated.

ballistics_bridge_free^⚠

Release a response produced by the bridge calls. NULL is a no-op.