chore(docs): documentation

Author: AKOrojo

Cargo.lock

@@ -174,6 +174,18 @@ pub fn extract_flows_with_config(
             format_duration(elapsed),
             format_count(rate as usize)
         );
+
+        let (total_drops, flows_with_drops) = count_dropped_segments(&conversations);
+        if total_drops > 0 {
+            eprintln!(
+                "[!] Warning: {} TCP segments dropped across {} flows (buffer/fragment limits exceeded)",
+                format_count(total_drops as usize),
+                format_count(flows_with_drops),
+            );
+            eprintln!(
+                "[!] Tip: increase max_reassembly_buffer or max_ooo_fragments to capture more data"
+            );
+        }
         eprintln!();
     }
     Ok(conversations)
@@ -265,11 +277,40 @@ where
             format_count(conversations.len())
         );
         eprintln!("[+] Wall time: {}", format_duration(elapsed));
+
+        // Report reassembly drops
+        let (total_drops, flows_with_drops) = count_dropped_segments(&conversations);
+        if total_drops > 0 {
+            eprintln!(
+                "[!] Warning: {} TCP segments dropped across {} flows (buffer/fragment limits exceeded)",
+                format_count(total_drops as usize),
+                format_count(flows_with_drops),
+            );
+            eprintln!(
+                "[!] Tip: increase max_reassembly_buffer or max_ooo_fragments to capture more data"
+            );
+        }
         eprintln!();
     }
     Ok(conversations)
 }
 
+/// Count total dropped TCP segments across all conversations.
+fn count_dropped_segments(conversations: &[ConversationState]) -> (u64, usize) {
+    let mut total_drops: u64 = 0;
+    let mut flows_with_drops: usize = 0;
+    for conv in conversations {
+        if let ProtocolState::Tcp(ref tcp) = conv.protocol_state {
+            let drops = tcp.total_dropped_segments();
+            if drops > 0 {
+                total_drops += drops;
+                flows_with_drops += 1;
+            }
+        }
+    }
+    (total_drops, flows_with_drops)
+}
+
 /// Extract flows directly from a capture file (PCAP or PcapNG).
 ///
 /// Streams packets from disk — never loads the entire file into memory.

crates/stackforge-core/src/flow/mod.rs

@@ -182,8 +182,7 @@ impl ConversationTable {
 
             if let ProtocolState::Tcp(ref mut tcp_state) = entry.value_mut().protocol_state {
                 // Skip buffers already on disk
-                if tcp_state.reassembler_fwd.is_spilled()
-                    && tcp_state.reassembler_rev.is_spilled()
+                if tcp_state.reassembler_fwd.is_spilled() && tcp_state.reassembler_rev.is_spilled()
                 {
                     consecutive_skips += 1;
                     continue;

crates/stackforge-core/src/flow/table.rs

@@ -4254,6 +4254,34 @@ impl PyConversation {
         }
     }
 
+    /// Number of TCP segments dropped due to reassembly buffer/fragment limits.
+    /// Returns 0 for non-TCP flows.
+    #[getter]
+    fn dropped_segments(&self) -> u64 {
+        match &self.inner.protocol_state {
+            stackforge_core::ProtocolState::Tcp(tcp) => tcp.total_dropped_segments(),
+            _ => 0,
+        }
+    }
+
+    /// Number of forward-direction TCP segments dropped.
+    #[getter]
+    fn dropped_segments_fwd(&self) -> u64 {
+        match &self.inner.protocol_state {
+            stackforge_core::ProtocolState::Tcp(tcp) => tcp.dropped_segments_fwd,
+            _ => 0,
+        }
+    }
+
+    /// Number of reverse-direction TCP segments dropped.
+    #[getter]
+    fn dropped_segments_rev(&self) -> u64 {
+        match &self.inner.protocol_state {
+            stackforge_core::ProtocolState::Tcp(tcp) => tcp.dropped_segments_rev,
+            _ => 0,
+        }
+    }
+
     /// Z-Wave home ID, or None for non-Z-Wave flows.
     #[getter]
     fn zwave_home_id(&self) -> Option<u32> {