Document FFI safety contracts for bridge entry points

[Sanjays2402]

What

The two C ABI entry points exposed to the iOS shell — goose_bridge_handle_json and goose_bridge_free_string in Rust/core/src/bridge.rs — are declared pub unsafe extern "C" but ship without a documented safety contract. Clippy flags both with missing_safety_doc, and more importantly the bridge is the cross-language interface, so its preconditions shouldn't have to be reconstructed from the implementation.

This PR adds rustdoc # Safety sections covering:

• pointer validity, null handling, and UTF-8 expectations for request_json
• aliasing rules for the duration of the call
• ownership transfer of the returned C string and the requirement to release it through goose_bridge_free_string (not free(3) — the Rust allocator backing CString is not guaranteed to match the host's, and Swift's swift_demangle-style helpers can hide this)
• double-free and foreign-allocator pitfalls on the free side

Treating this header as a stable contract is also the spirit of #2 — a documented safety contract is a prerequisite for the C ABI being something a future Android/JNI or Flutter/Dart FFI port can rely on without reading Rust source.

Why this matters in practice

The Swift bridge code (GooseRustBridge.swift) already has to obey these rules implicitly. Documenting them:

1. Locks the contract in the same place as the implementation, so it stays correct when the Rust side evolves.
2. Surfaces concrete pitfalls (mismatched allocator, double-free, lifetime of request_json) to any future contributor wiring a new platform shell.
3. Makes the next clippy run quieter on the file that matters most for soundness.

Change

Rust/core/src/bridge.rs only — two doc-comment blocks added, no code changes.

Verification

• cargo build --lib → clean (1m 23s, no new warnings, no new errors).
• cargo clippy --lib --no-deps → the two missing_safety_doc warnings on bridge.rs:2505 and bridge.rs:2529 are gone (0 remaining for that lint on this file).
• No behaviour change. Pure documentation.

Test plan

• Builds clean on macOS host (cargo build --lib)
• Clippy missing_safety_doc warnings on bridge entry points resolved
• CI build on iOS targets stays green (no code change, expected to pass)

Notes

• Kept the diff minimal — no rustfmt reflow, no clippy --fix sweep, nothing outside the two functions. If you'd like me to follow up with a broader safety/clippy pass (there are ~120 other warnings, mostly collapsible_if and too_many_arguments style nits), happy to send that as a separate PR.
• I'm running on a Mac without full Xcode, so I haven't built the iOS app — only the Rust core. Flagging in case anything iOS-side surprises you.

[tigercraft4]

Missing thread-safety contract.

The # Safety section correctly covers pointer validity, UTF-8, aliasing for the duration of a single call, and ownership transfer. What is not stated: whether goose_bridge_handle_json is safe to call concurrently from multiple threads.

If the bridge dispatches into stateful Rust (SQLite via rusqlite, any global), concurrent calls could race. If it is safe (because each call opens its own connection and the Rust side is stateless), that guarantee is as important to document as the pointer invariants — it determines whether a Swift caller can dispatch bridge calls from concurrent DispatchQueues without a lock.

Suggest adding: /// This function may be called concurrently from multiple threads — [safe/unsafe because ...]

[tigercraft4]

Doc-drift risk — no CI hook keeps the safety text in sync with behavior.

The goose_bridge_free_string safety section correctly documents ownership transfer and the double-free pitfall. However, if the implementation changes (e.g. the allocation strategy behind CString changes, or a wrapper is added), these docs will silently become wrong.

Minimum mitigation: reference the exact implementation so a future maintainer editing the code knows to update the doc:

/// Releases the string by calling [`CString::from_raw`] on `value`,
/// which reclaims the memory via the Rust allocator that produced it
/// (see the `string_to_c_string` helper). Do not pass a pointer
/// allocated by any other means.