From 824a266303b4f8e682a35823534e7d9c4167e709 Mon Sep 17 00:00:00 2001
From: pitboss <pitboss@local>
Date: Fri, 22 May 2026 03:50:02 -0500
Subject: [PATCH] [pitboss/grind] cleanup session-0012 (20260522T043516Z-29b8)

---
 docs/detectors/taint.md |  2 +-
 docs/serve.md           |  2 +-
 src/callgraph.rs        | 16 +++++++++++-----
 src/taint/mod.rs        |  3 ++-
 4 files changed, 15 insertions(+), 8 deletions(-)

diff --git a/docs/detectors/taint.md b/docs/detectors/taint.md
index 95618c84..cb703278 100644
--- a/docs/detectors/taint.md
+++ b/docs/detectors/taint.md
@@ -59,7 +59,7 @@ Higher confidence:
 Lower confidence:
 - Path-validated taint (`path_validated: true`).
 - Source is a database read or internal file (pre-validated at insertion is common).
-- Engine note `ForwardBailed` / `PathWidened`. Use `--require-converged` to drop these in strict gates.
+- Any non-informational engine note (`SsaLoweringBailed`, `ParseTimeout`, `PredicateStateWidened`, `PathEnvCapped`, `WorklistCapped`, etc.). Use `--require-converged` to drop over-report and bail notes in strict gates.
 
 ## Tuning
 
diff --git a/docs/serve.md b/docs/serve.md
index 758dcfe1..038e97ee 100644
--- a/docs/serve.md
+++ b/docs/serve.md
@@ -98,7 +98,7 @@ Clicking through opens the **flow visualiser**: a numbered walk from source to s
 
 <p align="center"><img src="assets/screenshots/docs/serve-finding-detail.png" alt="Nyx finding detail: HIGH taint-unsanitised-flow showing source → call → sink steps, How to fix guidance, and evidence panel" width="900"/></p>
 
-Engine notes call out when precision was bounded for that finding (`OriginsTruncated`, `PointsToTruncated`, `PathWidened`, `ForwardBailed`, etc.). Anything tagged `under-report` means the emitted flow is real and the result set is a lower bound; `over-report` means widening or bail. `--require-converged` in the CLI drops the over-report ones for strict gates.
+Engine notes call out when precision was bounded for that finding (`OriginsTruncated`, `PointsToTruncated`, `WorklistCapped`, `PredicateStateWidened`, `SsaLoweringBailed`, etc.). Each note carries a direction tag: `under-report` means the emitted flow is real and the result set is a lower bound; `over-report` means widening dropped a guard; `bail` means analysis aborted before producing a trustworthy result. `--require-converged` in the CLI drops over-report and bail notes for strict gates.
 
 ### Triage
 
diff --git a/src/callgraph.rs b/src/callgraph.rs
index 1b2ebaab..0ed97141 100644
--- a/src/callgraph.rs
+++ b/src/callgraph.rs
@@ -1005,10 +1005,16 @@ pub fn scc_spans_files(cg: &CallGraph, scc: &[NodeIndex]) -> bool {
     iter.any(|n| cg.graph[*n].namespace.as_str() != first_ns)
 }
 
-/// Like [`scc_file_batches`] but annotates each batch with whether any
-/// contributing SCC has mutual recursion (`len > 1`).
+/// Map SCC topological order to an ordered sequence of file-path batches
+/// annotated with whether any contributing SCC is mutually recursive
+/// (`len > 1`) or cross-file.
 ///
-/// Returns `(ordered_batches, orphan_files)`.
+/// A file is placed in the earliest batch where any of its functions appear
+/// (min topo index), so leaf callees become available before the callers
+/// that depend on them.
+///
+/// Returns `(ordered_batches, orphan_files)`. Orphans are paths from
+/// `all_files` that have no functions in the call graph.
 pub fn scc_file_batches_with_metadata<'a>(
     cg: &CallGraph,
     analysis: &CallGraphAnalysis,
@@ -1089,8 +1095,8 @@ pub fn scc_file_batches_with_metadata<'a>(
 ///
 /// Returns `(ordered_batches, orphan_files)` where orphan_files are paths
 /// from `all_files` that have no functions in the call graph.
-#[allow(dead_code)] // kept for tests; production callers use scc_file_batches_with_metadata
-pub fn scc_file_batches<'a>(
+#[cfg(test)]
+pub(super) fn scc_file_batches<'a>(
     cg: &CallGraph,
     analysis: &CallGraphAnalysis,
     all_files: &'a [PathBuf],
diff --git a/src/taint/mod.rs b/src/taint/mod.rs
index ed47877e..bf82d9a8 100644
--- a/src/taint/mod.rs
+++ b/src/taint/mod.rs
@@ -61,7 +61,8 @@
 //! user_input`, `path_validated: false`, symbolic witness produced.
 //!
 //! Lower confidence: path-validated taint, source is a database read or
-//! internal file, engine note `ForwardBailed` / `PathWidened`.
+//! internal file, any non-informational `EngineNote` (e.g.
+//! `SsaLoweringBailed`, `PredicateStateWidened`, `WorklistCapped`).
 //!
 //! # Submodules
 //!