refactor(fspy-shm): split what the channel reports from what it panics on

The CLOSED gate now means one thing: the region had no room. That is the
only failure `shm_io` owns, since the region's size is the only thing it
controls. `report_lost_record` goes with that, and the gate loses its
second meaning.

Everything else a sender can hit is a defect in this crate, so the channel
layer panics instead of reporting. `Sender::send` panics when a record's
serialized size disagrees with the bytes it writes, and `sender()` panics
when the region is there but cannot be opened, mapped, or attached to.

A missing backing file stays an error, because it is not a failure at all:
the receiver removed it, so it has already stopped collecting and this
process is working past the boundary. That distinction is what lets the
rest abort. A process that cannot attach has no way to tell the receiver it
recorded nothing, and a trace that silently omits every access a process
made is worse than a build that stops.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: wan9chi

crates/fspy_client_unix/src/lib.rs

@@ -54,10 +54,13 @@ impl Client {
 
         let ipc_sender = match encoded_payload.payload.ipc_channel_conf.sender() {
             Ok(sender) => Some(sender),
+            // The only failure `sender` returns is a channel that has
+            // already closed, which happens when this process starts after
+            // the root target exited. Everything it does from here is past
+            // the receiver's boundary, so recording nothing loses nothing.
+            // Anything worse stops the process inside `sender` instead.
             Err(err) => {
-                // This can happen if the process starts after the root target
-                // has exited and the receiver has closed the channel.
-                eprintln!("fspy: failed to create ipc sender: {err}");
+                eprintln!("fspy: the trace channel has closed: {err}");
                 None
             }
         };

crates/fspy_preload_windows/src/windows/client.rs

@@ -18,16 +18,18 @@ impl<'a> Client<'a> {
 
         let ipc_sender = match payload.channel_conf.sender() {
             Ok(sender) => Some(sender),
+            // The only failure `sender` returns is a channel that has
+            // already closed, which happens when this process starts after
+            // the root target exited. Everything it does from here is past
+            // the receiver's boundary, so recording nothing loses nothing.
+            // Anything worse stops the process inside `sender` instead.
             Err(err) => {
-                // this can happen if the process is started after the root target process has exited.
-                // By that time the channel would have been closed in the receiver side.
-                // In this case we just leave a message and skip sending any path accesses.
                 #[expect(
                     clippy::print_stderr,
                     reason = "preload library uses stderr for debug diagnostics"
                 )]
                 {
-                    eprintln!("fspy: failed to create ipc sender: {err}");
+                    eprintln!("fspy: the trace channel has closed: {err}");
                 }
                 None
             }

crates/fspy_shared/src/ipc/channel/mod.rs

@@ -165,12 +165,19 @@ impl Drop for ShmKeeper {
 impl ChannelConf {
     /// Creates a sender.
     ///
-    /// Never blocks. Fails when the receiver has already closed the channel
-    /// or dropped, because the backing file is removed either way. A close
-    /// also shuts the region's gate before removing it, so a sender that
-    /// attaches in that window still finds a closed channel; a receiver
-    /// that is merely dropped only removes the file, and a removal that
-    /// fails there leaves the region attachable.
+    /// Never blocks. Fails only when the channel is already over: the
+    /// receiver removed the backing file, or it sealed the region before
+    /// removing it and a sender caught the gate in between. Either way
+    /// whatever this process does next happens past the receiver's
+    /// boundary, so skipping its records loses nothing.
+    ///
+    /// # Panics
+    ///
+    /// When the channel is there but cannot be attached to: the file
+    /// refuses to open or map, or it cannot hold the protocol. A process
+    /// with no writer has no way to tell the receiver it recorded nothing,
+    /// and a trace that silently omits every access it made is worse than
+    /// no trace, so it stops here instead.
     #[expect(
         clippy::missing_errors_doc,
         reason = "error conditions are self-evident from return type"
@@ -180,24 +187,30 @@ impl ChannelConf {
         // the preload contexts that create senders (pre-`main` constructors,
         // the Windows loader lock).
         let arena = fspy_nostd_alloc::arena();
-        let shm_path = self.shm_id.to_os_c_string_in(&arena).ok_or_else(|| {
-            io::Error::new(io::ErrorKind::InvalidData, "invalid shared-memory path")
-        })?;
-        let mapping = fspy_shm::open(shm_path.as_c_str().as_thin())
-            .map_err(shm_error_to_io)?
-            .map()
-            .map_err(shm_error_to_io)?;
+        let shm_path = self
+            .shm_id
+            .to_os_c_string_in(&arena)
+            .expect("the channel's own shared-memory path is not a valid C string");
+        let handle = match fspy_shm::open(shm_path.as_c_str().as_thin()) {
+            Ok(handle) => handle,
+            Err(error) => {
+                let error = shm_error_to_io(error);
+                // The receiver removed the backing file, so it has already
+                // stopped collecting.
+                if error.kind() == io::ErrorKind::NotFound {
+                    return Err(error);
+                }
+                panic!("cannot open the shared-memory channel: {error}");
+            }
+        };
+        let mapping = handle.map().unwrap_or_else(|error| {
+            panic!("cannot map the shared-memory channel: {}", shm_error_to_io(error))
+        });
         // SAFETY: `mapping` is a freshly mapped shared memory region created
         // zero-initialized by `channel` and accessed only through the
         // `shm_io` protocol by every attached process.
-        let Some(writer) = (unsafe { ShmWriter::new(mapping) }) else {
-            // A truncated or foreign file fails here — it never panics the
-            // host process.
-            return Err(io::Error::new(
-                io::ErrorKind::InvalidData,
-                "shared-memory region cannot host the channel",
-            ));
-        };
+        let writer = unsafe { ShmWriter::new(mapping) }
+            .expect("the shared-memory region cannot hold the channel");
         if writer.is_closed() {
             return Err(io::Error::new(
                 io::ErrorKind::BrokenPipe,
@@ -215,32 +228,33 @@ pub struct Sender {
 impl Sender {
     /// Serializes one record into a committed frame.
     ///
-    /// A record that cannot be sent is skipped, because that is all a
-    /// sender inside an intercepted call can do — but never silently. A
-    /// failed claim already reports itself: for space by setting the CLOSED
-    /// gate, or as closed, which means the record belongs past the
-    /// receiver's boundary. The remaining ways to give up are this
-    /// sender's own, so it reports them, and the seal then refuses to hand
-    /// back a set of frames that is missing one.
+    /// A claim the channel refuses is skipped, because that is all a sender
+    /// inside an intercepted call can do: the channel has closed, so the
+    /// record belongs past the receiver's boundary, or the region is full
+    /// and the failed claim already set the CLOSED gate to say so.
+    ///
+    /// # Panics
+    ///
+    /// When the record's serialized size disagrees with the bytes it then
+    /// writes. Nothing the caller passes can cause that, so it is a defect
+    /// in this crate or its codec, and a trace built on it would be wrong
+    /// in ways the receiver cannot see.
     pub fn send<T: SchemaWrite<DefaultConfig, Src = T>>(&self, value: &T) {
         let Ok(serialized_size) = T::serialized_size(value) else {
-            self.writer.report_lost_record();
-            return;
+            panic!("a record cannot report its serialized size");
         };
         let Ok(Some(frame_size)) = usize::try_from(serialized_size).map(NonZeroUsize::new) else {
-            self.writer.report_lost_record();
-            return;
+            panic!("a record reports a serialized size of {serialized_size} bytes");
         };
         let Ok(mut frame) = self.writer.claim_frame(frame_size) else {
             return;
         };
         let mut buf: &mut [u8] = &mut frame;
-        if T::serialize_into(&mut buf, value).is_err() || !buf.is_empty() {
-            // The frame is abandoned — the receiver ignores its slot — so
-            // the loss needs reporting on its own.
-            self.writer.report_lost_record();
-            return;
-        }
+        let written = T::serialize_into(&mut buf, value);
+        assert!(
+            written.is_ok() && buf.is_empty(),
+            "a record wrote fewer bytes than the {serialized_size} it reported"
+        );
         frame.finish();
     }
 }

crates/fspy_shared/src/ipc/channel/shm_io/README.md

@@ -36,7 +36,7 @@ Where the table ends and payloads begin never moves. Claiming needs no retry loo
 - **The process died,** mid-claim or mid-fill. The slot stays zero and the receiver ignores it. No cleanup code runs, because none exists.
 - **The process abandoned the frame** and kept going. The slot stays zero and the receiver ignores that too, since it cannot tell the two apart.
 
-So the channel asks one thing of its users: **publish a record before performing the action it describes.** A dead writer's missing record then describes an action that never happened, and a record refused after the seal describes one performed after the channel closed. The receiver drops both. A writer that records after acting loses records with nothing said. A writer that abandons a frame and acts anyway calls `ShmWriter::report_lost_record`.
+So the channel asks one thing of its users: **publish a record before performing the action it describes.** A dead writer's missing record then describes an action that never happened, and a record refused after the seal describes one performed after the channel closed. The receiver drops both. A writer that records after acting, or that abandons a frame and acts anyway, breaks the rule and loses records with nothing said. The channel cannot see either one.
 
 ## When the region fills up
 

crates/fspy_shared/src/ipc/channel/shm_io/layout.rs

@@ -10,8 +10,9 @@
 use std::{num::NonZeroU32, ptr::NonNull, sync::atomic::AtomicU64};
 
 /// The CLOSED gate bit of the claim counter. The receiver sets it when it
-/// seals, and so does any failed claim, which is how it reports the loss
-/// (rule 1).
+/// seals, and so does a claim the region had no room for, which is how it
+/// reports the loss (rule 1). Nothing else sets it: what a writer cannot
+/// record for its own reasons is not this protocol's to report.
 ///
 /// A bit rather than a value to compare against, so it survives the
 /// increment of a writer that arrives late. Counting cannot reach it: that

crates/fspy_shared/src/ipc/channel/shm_io/mod.rs

@@ -9,9 +9,9 @@
 //! The channel asks one thing of its writers: **publish a record before
 //! performing the action it describes.** A record that never arrives then
 //! describes an action that never happened, and one refused after the seal
-//! describes an action performed after the receiver stopped collecting.
-//! [`ShmWriter::report_lost_record`] covers the case left over, where a
-//! writer gives up on a record and acts anyway.
+//! describes an action performed after the receiver stopped collecting. A
+//! writer that gives up on a record and performs the action anyway breaks
+//! the rule, and this protocol cannot tell that it did.
 //!
 //! `README.md` in this directory describes the region, the claim sequence,
 //! and why the receiver can borrow frames out of shared memory. [`layout`]
@@ -343,24 +343,6 @@ mod tests {
         assert!(sealed.unwrap_err() == SealError::Closed);
     }
 
-    /// A writer that gives up on a frame it already claimed, or before it
-    /// could claim one, has no failed claim to report the loss for it.
-    #[test]
-    fn a_reported_loss_fails_the_seal() {
-        let shm = MockedShm::alloc(1024);
-        // SAFETY: see `single_thread_basic`.
-        let writer: ShmWriter<_, S> = unsafe { ShmWriter::new(shm.clone()) }.unwrap();
-        assert!(writer.try_write_frame(b"kept"));
-
-        assert!(!writer.is_closed());
-        writer.report_lost_record();
-        assert!(writer.is_closed());
-
-        // SAFETY: see `collect_frames`.
-        let sealed = unsafe { ShmReader::seal::<S>(shm) };
-        assert!(sealed.unwrap_err() == SealError::Closed);
-    }
-
     #[test]
     fn claims_after_seal_are_gated_without_poisoning() {
         let shm = MockedShm::alloc(1024);

crates/fspy_shared/src/ipc/channel/shm_io/writer.rs

@@ -67,20 +67,6 @@ impl<M: AsRawSlice, const SLOTS: usize> ShmWriter<M, SLOTS> {
         Some(Self { mapped, _mem: mem })
     }
 
-    /// Reports a record this writer could not write, which closes the
-    /// channel and fails its seal: whatever the receiver collects is no
-    /// longer all of them.
-    ///
-    /// A claim that fails for space reports itself. This covers a writer
-    /// that gives up for its own reasons, before or after claiming, and
-    /// then performs the operation the record described. Dropping the
-    /// frame reports nothing on its own: the receiver cannot tell an
-    /// abandoned slot from one whose writer died, and a writer that died
-    /// never performed its operation.
-    pub fn report_lost_record(&self) {
-        self.mapped.claims().fetch_or(CLOSED, Ordering::Relaxed);
-    }
-
     /// Whether the CLOSED gate is set, by a seal or by a failed claim.
     pub fn is_closed(&self) -> bool {
         self.mapped.claims().load(Ordering::Relaxed) & CLOSED != 0
@@ -181,8 +167,9 @@ fn fitted_offset(start: u64, len: u32, payload_len: u32) -> Option<u32> {
 /// [`FrameMut::finish`] is the only way to show the payload to the
 /// receiver. Dropping the frame gives the claim up: the slot stays
 /// unfinished and the receiver ignores it, as if the writer had died
-/// there. A writer that drops a frame and performs the operation anyway
-/// owes the channel a [`ShmWriter::report_lost_record`].
+/// there. The two look identical from the outside, which is why a writer
+/// that drops a frame and performs the operation anyway breaks the rule
+/// this channel rests on.
 #[derive(Debug)]
 pub struct FrameMut<'a> {
     slot: &'a AtomicU64,