docs: add missing why-comments across all merge pipeline files

Per CODE_STYLE.md: comments should convey intent, not implementation.
Added explanations for num_merge_ops lineage, known_split_ids rebuild
heuristic, output dir isolation, empty merge handling, scratch dir
lifetime, permit Drop safety, publisher setter ordering, and feedback
loop guard conditions.

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

Author: g-talbot

quickwit/quickwit-indexing/src/actors/merge_scheduler_service.rs

@@ -267,6 +267,7 @@ impl MergeSchedulerService {
             } = PeekMut::pop(next_merge);
             // The permit is owned by the task and released via Drop when
             // the executor finishes, triggering PermitReleased back here.
+            // Drop-based release ensures the semaphore is freed even on panic.
             let parquet_merge_task = ParquetMergeTask {
                 merge_operation,
                 merge_permit,

quickwit/quickwit-indexing/src/actors/metrics_pipeline/parquet_merge_executor.rs

@@ -96,7 +96,8 @@ impl Handler<ParquetMergeScratch> for ParquetMergeExecutor {
             "executing parquet merge"
         );
 
-        // Create output directory for the merged files.
+        // Separate output subdirectory so the merge engine's temp files
+        // don't collide with the downloaded inputs in scratch_directory.
         let output_dir = scratch.scratch_directory.path().join("merged_output");
         std::fs::create_dir_all(&output_dir)
             .context("failed to create merge output directory")
@@ -142,6 +143,7 @@ impl Handler<ParquetMergeScratch> for ParquetMergeExecutor {
             }
         };
 
+        // Empty output is valid (all input rows were empty). Nothing to publish.
         if outputs.is_empty() {
             info!(
                 merge_split_id = %merge_split_id,

quickwit/quickwit-indexing/src/actors/metrics_pipeline/parquet_merge_planner.rs

@@ -265,6 +265,8 @@ impl ParquetMergePlanner {
                 known.insert(split.split_id.as_str().to_string());
             }
         }
+        // If rebuild didn't shrink the set by at least half, something may be
+        // leaking IDs (splits not being dropped from the inventory).
         if known.len() * 2 >= self.known_split_ids.len() {
             warn!(
                 known_split_ids_len_after = known.len(),

quickwit/quickwit-indexing/src/actors/publisher.rs

@@ -67,7 +67,9 @@ impl Publisher {
         }
     }
 
-    /// Set the Parquet merge planner mailbox for merge feedback.
+    /// Sets the Parquet merge planner mailbox for merge feedback.
+    /// Post-construction setter because the Publisher is created before the
+    /// planner mailbox is available (bottom-up actor spawn order).
     #[cfg(feature = "metrics")]
     pub fn set_parquet_merge_planner_mailbox(
         mut self,

quickwit/quickwit-parquet-engine/src/merge/metadata_aggregation.rs

@@ -95,7 +95,8 @@ pub fn merge_parquet_split_metadata(
         }
     }
 
-    // num_merge_ops: max(inputs) + 1
+    // Each merge adds one to the lineage depth. The policy uses this to
+    // decide when a split is "mature" (reached max_merge_ops).
     let num_merge_ops = inputs
         .iter()
         .map(|s| s.num_merge_ops)