fix(v9.1.0): non-blocking prev_drained_is_set + truthful flatfiles doc

- `ThetaDataDx::prev_drained_is_set()` now uses `try_lock()` instead
  of `lock()`. Returning `true` on contention is the institutionally
  safe choice: the FFI `_free` path uses this signal to decide
  whether to wait on the drain barrier, and "wait" is the correct
  fail-safe when a stop is actively in flight. The contention window
  is microseconds (the lock is held only across the
  `Option<Arc<AtomicBool>>` swap), so the false-positive cost is
  negligible. Poison is recovered the same way the previous `lock()`
  path did, so behaviour on a poisoned mutex is unchanged.
- `flatfile_request_raw` rustdoc no longer claims the INDEX walker
  and FIT decoder are tracked as TODOs — both shipped in the
  flat-files wave and live behind `flatfile_request_decoded`. The
  raw-bytes path documents that it returns the unparsed vendor
  format for callers that want to keep the on-disk layout.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: userFRM

crates/thetadatadx/src/client.rs

@@ -470,12 +470,28 @@ impl ThetaDataDx {
     /// FFI free paths use this to disambiguate the two `false` returns
     /// from `await_drain` (timeout vs. nothing-to-wait-on); only the
     /// former is a real concern worth surfacing in operator logs.
+    ///
+    /// **Non-blocking.** Uses `try_lock` on the internal slot mutex.
+    /// If the mutex is contended (another thread is mid-`stop_streaming`
+    /// or `reconnect_streaming` swapping the slot), this returns `true`
+    /// — the institutionally-safe answer, because the FFI `_free` path
+    /// uses this signal to decide whether to wait on the drain barrier,
+    /// and "wait" is the correct fail-safe when a stop is actively in
+    /// flight. The contention window is microseconds (the lock is held
+    /// only across the `Option<Arc<AtomicBool>>` swap), so the false-
+    /// positive cost is negligible.
     #[must_use]
     pub fn prev_drained_is_set(&self) -> bool {
-        self.prev_drained
-            .lock()
-            .unwrap_or_else(std::sync::PoisonError::into_inner)
-            .is_some()
+        match self.prev_drained.try_lock() {
+            Ok(guard) => guard.is_some(),
+            Err(std::sync::TryLockError::Poisoned(p)) => p.into_inner().is_some(),
+            Err(std::sync::TryLockError::WouldBlock) => {
+                // Mutex contended — another thread is mid-stop. Treat
+                // as "drain in progress" (true) so the FFI free path
+                // waits for the drain barrier rather than skipping it.
+                true
+            }
+        }
     }
 
     #[must_use]

crates/thetadatadx/src/flatfiles/request.rs

@@ -91,9 +91,10 @@ fn validate_date(date: &str) -> Result<(), Error> {
 /// **Output format**: a raw concatenation of every FLAT_FILE chunk
 /// payload, in receive order, **without** the framing headers. This is the
 /// same byte sequence the vendor jar accumulates internally before walking
-/// the index — to convert it to CSV one must implement the INDEX walker
-/// and per-data-type FIT decoder. Both are tracked as TODOs in
-/// [`crate::flatfiles`].
+/// the index. The INDEX walker and per-`(SecType, ReqType)` FIT decoder
+/// are exposed via [`crate::flatfiles::flatfile_request_decoded`];
+/// this function returns the raw bytes for callers that want to keep the
+/// on-disk vendor format unchanged.
 pub async fn flatfile_request_raw(
     creds: &Credentials,
     sec: SecType,