Document magic numbers and unsafe env var usage in tests

Author: tonyalaribe

src/buffered_write_layer.rs

@@ -10,7 +10,9 @@ use tokio::task::JoinHandle;
 use tokio_util::sync::CancellationToken;
 use tracing::{debug, error, info, instrument, warn};
 
-const MEMORY_OVERHEAD_MULTIPLIER: f64 = 1.2; // 20% overhead for DashMap, RwLock, schema refs
+// 20% overhead accounts for DashMap internal structures, RwLock wrappers,
+// Arc<Schema> refs, and Arrow buffer alignment padding
+const MEMORY_OVERHEAD_MULTIPLIER: f64 = 1.2;
 
 #[derive(Debug, Default)]
 pub struct RecoveryStats {
@@ -95,6 +97,7 @@ impl BufferedWriteLayer {
         let estimated_size = (batch_size as f64 * MEMORY_OVERHEAD_MULTIPLIER) as usize;
 
         let max_bytes = self.max_memory_bytes();
+        // Hard limit at 120% provides headroom for in-flight writes while preventing OOM
         let hard_limit = max_bytes.saturating_add(max_bytes / 5);
 
         for _ in 0..100 {

src/mem_buffer.rs

@@ -11,7 +11,9 @@ use std::sync::RwLock;
 use std::sync::atomic::{AtomicI64, AtomicUsize, Ordering};
 use tracing::{debug, info, instrument, warn};
 
-const BUCKET_DURATION_MICROS: i64 = 10 * 60 * 1_000_000; // 10 minutes in microseconds
+// 10-minute buckets balance flush granularity vs overhead. Shorter = more flushes,
+// longer = larger Delta files. Matches default flush interval for aligned boundaries.
+const BUCKET_DURATION_MICROS: i64 = 10 * 60 * 1_000_000;
 
 /// Check if two schemas are compatible for merge.
 /// Compatible means: all existing fields must be present in incoming schema with same type,

tests/test_dml_operations.rs

@@ -17,14 +17,13 @@ mod test_dml_operations {
         keys: Vec<(String, Option<String>)>,
     }
 
+    // SAFETY: All tests using EnvGuard are marked #[serial], ensuring single-threaded
+    // execution. No other threads read env vars during test execution.
     impl EnvGuard {
         fn set(key: &str, value: &str) -> Self {
             let old = std::env::var(key).ok();
-            // SAFETY: Tests run serially via #[serial] attribute
             unsafe { std::env::set_var(key, value) };
-            Self {
-                keys: vec![(key.to_string(), old)],
-            }
+            Self { keys: vec![(key.to_string(), old)] }
         }
 
         fn add(&mut self, key: &str, value: &str) {