Document unsafe contracts and stop reusing poisoned state

portal/src/bridge.rs

@@ -178,6 +178,8 @@ impl Bridge {
                 let mut byte = 0u8;
                 // Per-call nonblocking peek leaves the shared descriptor flags
                 // and response bytes untouched for the request reader.
+                // SAFETY: byte is writable for the requested single byte, and the locked reader
+                // retains the socket descriptor.
                 let result = unsafe {
                     libc::recv(
                         reader.get_ref().as_raw_fd(),

portal/src/bridge/tests.rs

@@ -163,12 +163,16 @@ async fn peer_watch_keeps_descriptor_flags_and_response_bytes_untouched() {
     use std::os::fd::AsRawFd;
 
     let (bridge, mut server) = pair();
+    // SAFETY: F_GETFL only reads flags for the bridge-owned descriptor and takes no pointer
+    // argument.
     let flags = unsafe { libc::fcntl(bridge.0.shutdown.as_raw_fd(), libc::F_GETFL) };
     server.write_all(b"x").unwrap();
     tokio::time::timeout(Duration::from_secs(1), bridge.closed())
         .await
         .unwrap();
     assert_eq!(
+        // SAFETY: F_GETFL only reads flags for the bridge-owned descriptor and takes no pointer
+        // argument.
         unsafe { libc::fcntl(bridge.0.shutdown.as_raw_fd(), libc::F_GETFL) },
         flags
     );

portal/src/capture.rs

@@ -422,6 +422,8 @@ impl Dispatch<frame::ZwlrScreencopyFrameV1, ()> for State {
                         return Err(std::io::Error::last_os_error().to_string());
                     }
 
+                    // SAFETY: memfd_create succeeded above and returned a fresh descriptor whose
+                    // ownership transfers to File.
                     let file = unsafe { File::from_raw_fd(fd) };
                     file.set_len(bytes as u64).map_err(|e| e.to_string())?;
                     // SAFETY: the file has the checked mapping length and lives with the mapping.

portal/src/parent.rs

@@ -107,11 +107,13 @@ impl Parent {
         else {
             return Err("Portal parenting requires Wayland".into());
         };
-        // The window lends live handles; the borrowed backend never owns the display.
+        // SAFETY: The Iced runtime retains its display connection while this parent attachment
+        // borrows the native handles.
         let backend = unsafe {
             wayland_client::backend::Backend::from_foreign_display(display.display.as_ptr().cast())
         };
         let connection = Connection::from_backend(backend);
+        // SAFETY: The native window handle identifies a live wl_surface on the borrowed display.
         let id = unsafe {
             wayland_client::backend::ObjectId::from_ptr(
                 wl_surface::WlSurface::interface(),