Imported from chogng/ash (ash-rs/vendor/livekit-rust-sdks/webrtc-sys/AGENTS.md). Install upstream with npx skills add chogng/ash --skill webrtc-sys. Copyright stays with the author.

AGENTS.md

C++ and cxx-bridge code in this crate. Follow the repository-root AGENTS.md for Rust-wide rules; this file covers native ownership and teardown.

Memory lifecycle

C++ shared_ptr graphs and WebRTC observer registrations can leak independently of Rust Drop.

• Treat every shared_ptr copy, callback capture, observer registration, and spawned thread as an ownership edge. If an owner transitively stores the callback, the callback must not strongly capture that owner.
• Use weak_ptr for non-owning back-references. A strong back-reference is allowed only when teardown explicitly unregisters or clears it before releasing the owner, and a lifecycle regression test proves cleanup.
• A callback stored by an object must not capture a strong clone of that same object. Reviewers must flag C++ lambdas capturing shared_ptr/shared_from_this when the receiver can retain the callback.
• Every thread, native handle, observer, timer, and queue must have a named owner and deterministic shutdown path. Threads must be joined; observers must be unregistered; native resources (CUDA contexts, FDs, WebRTC factories) must be released on the teardown path.
• For lifecycle-sensitive changes, test observable destruction: weak_ptr::expired(), native handle maps empty, and thread/FD counts returning near baseline. RAII destructors alone are not evidence that destruction occurs because reference cycles prevent them from running.
• Any new C++-reachable feature must add a repeated initialize → use → disconnect/drop → shutdown workload. Include success, failure/cancellation, and partial-initialization teardown where applicable.
• Review ownership changes by sketching the strong-reference graph. Every cycle must contain a weak edge or an explicit, tested unlink operation.

When reviewing changed code, search for shared_from_this, shared_ptr copies into lambdas, listener/observer registration, and native handle stores. Report lifecycle risks even when the code compiles.