sparkforensics-cli 0.1.0 → 0.2.0

package/vendor-core/detectors.js

@@ -1,33 +1,23 @@
 import { pathBasename, formatBytes, nsToMs, IMPACT_BAND_ORDER } from './format-utils.js';
 import { scanRelationId } from './plan-summary.js';
-import { computeTotalCores } from './core-count.js';
+import { computePeakConcurrentCores, computePeakConcurrentExecutorCount } from './core-count.js';
 import { walkPlanTree } from './plan-tree-walk.js';
 import { computeCoreLocalityRatio } from './core-locality-ratio.js';
 import { estimateSingleStage,                                              } from './occupancy.js';
+import { isExchangeNode, isBroadcastExchangeNode } from './plan-node-detail.js';
                                                                
 
 const MB = 1024 * 1024;
 const GB = 1024 * MB;
 const TB = 1024 * GB;
 
-// ---------------------------------------------------------------------------
 // Local runtime shapes.
 //
-// `types.ts`'s `Stage`/`SqlExecution`/`SparkAppInfo`/`AppModel` describe the
-// *posted* AppModel surface at a level of detail that suits the view layer
-// (both carry a catch-all `[key: string]: unknown` index signature for
-// anything beyond their few named fields). This file needs the FULL set of
-// fields `finalizeStage` (src/stage-quantiles.ts) actually computes and
-// `event-handlers.ts`'s stage/sql/app records actually carry, accessed
-// directly (arithmetic, comparisons) rather than read-and-display, so an
-// index-signature-shaped type would force an `unknown` cast at nearly every
-// field access. Every field below is verified against a real access in this
-// file (or a helper it calls); none are speculative.
-//
-// `analyzer.js` (the only real caller of `detect()`, still plain JS) passes
-// whatever the parser actually produced, so these types describe reality,
-// not a narrowing of some existing stricter type; there is nothing unsound
-// about them being independent of `types.ts`'s `Stage`/`SqlExecution`.
+// types.ts's Stage/SqlExecution/SparkAppInfo describe the posted AppModel surface for the view
+// layer (with a catch-all index signature). This file needs the FULL set of fields finalizeStage
+// computes and event-handlers.ts records carry, accessed directly (arithmetic, comparisons), so
+// an index-signature type would force an `unknown` cast at nearly every access. Every field below
+// is verified against a real access here.
                                                                                       
                                 
                                                                
@@ -35,9 +25,18 @@ const TB = 1024 * GB;
  
                                                                   
                                                                    
-// Per-executor snapshot from a StageExecutorMetrics event (mergeStageRddInfo/
-// onStageExecutorMetrics): a loose bag of Spark's ExecutorMetrics field
-// names, only a few of which any detector reads.
+                                    
+                        
+                        
+               
+                     
+                        
+                      
+                     
+                       
+ 
+// Per-executor snapshot from a StageExecutorMetrics event: a loose bag of Spark's
+// ExecutorMetrics field names, only a few of which any detector reads.
                                            
                          
                                
@@ -81,6 +80,8 @@ const TB = 1024 * GB;
                          
                        
                                     
+                                                 
+                                                
  
 
                                   
@@ -116,27 +117,19 @@ const TB = 1024 * GB;
                        
                         
                             
-                                                                             
-                                                                
+                                                                                                 
                                 
                                 
  
 
-// The full context object analyzer.js's `analyze()` builds and passes as
-// every stage/sql detect()'s second argument, and as the sole argument for
-// 'app' scope (`d.detect(ctx)`). 'config' scope gets a narrower `{ app }`
-// (see auditConfig in analyzer.js), typed per-entry below instead of here.
+// The full context analyze() passes as every stage/sql detect()'s second arg, and as the sole
+// arg for 'app' scope. 'config' scope gets a narrower `{ app }` (auditConfig), typed per-entry.
 //
-// `app` is non-nullable here (unlike `AppModel.app: SparkAppInfo | null`):
-// `analyze()` only ever runs after a full parse, by which point `app` is
-// always populated; the `SparkAppInfo | null` nullability models the
-// in-progress-parse window this file never observes. This matches every
-// 'app'-scope entry below: most defensively write `ctx.app?.foo` anyway
-// (harmless on a non-nullable value), and `coldStart` reads `app.startTime`
-// with no guard at all, which only type-checks if `app` is non-nullable.
-// `auditConfig`'s separate config-scope target type keeps `app` nullable
-// instead, since `auditConfig(appModel.app)` (src/analyzer.js) really can be
-// called with a `null` app and every config-scope entry optional-chains it.
+// `app` is typed as non-nullable here (unlike AppModel.app), but incompleteRun, coldStart,
+// utilization, and autoscalingChurn defensively guard against null at runtime to tolerate
+// malformed/incomplete logs. Despite the type annotation, app may be null in edge cases, and
+// these detectors handle it gracefully. auditConfig's config-scope target keeps `app` nullable
+// instead.
                               
                    
                                      
@@ -145,17 +138,13 @@ const TB = 1024 * GB;
                                  
                                     
                                                 
-                                                                         
-                                                                       
-                                                                         
-                                                                 
-                            
+                                                                                             
+                                                                                                
                                              
  
 
-// `auditConfig(app)` (src/analyzer.js) calls every 'config'-scope entry's
-// `detect({ app })` directly with whatever `appModel.app` is at call time
-// (`SparkAppInfo | null`), independent of the full `DetectorCtx` above.
+// auditConfig(app) calls every config-scope detect({ app }) with whatever appModel.app is
+// (SparkAppInfo | null), independent of DetectorCtx.
                                        
                           
  
@@ -167,8 +156,7 @@ const TB = 1024 * GB;
                                                                                            
  
 
-// sparkDoctor SpillPressureDetector (5a) + SpillSkewDetector (5b).
-// Returns { magnitude } | null. Magnitude ∈ 'severe'|'high'|'medium'.
+// SpillPressureDetector (5a) + SpillSkewDetector (5b).
 function computeSpillMagnitude(
   stage                                                                                                    ,
   t                 ,
@@ -195,15 +183,9 @@ function pickDominantReason(reasons                                     )
   return [...reasons].sort((a, b) => b.count - a.count)[0].reason;
 }
 
-// Shared by every scope:'sql' detector below. `sql.get(executionId).stageIds`
-// (src/model-assembler.js) is always empty because parser-worker.js never
-// populates it, so stage linkage is derived the other way round, from each
-// stage's own (correctly populated) `sqlExecutionId`. Parameter type is
-// intentionally the minimal shape needed (not `DetectorStage`): callers
-// outside this file (Topbar.tsx, plan-node-detail.ts, plan-graph-model.ts)
-// pass `appModel.stages`, typed `Map<StageId, Stage>` per types.ts, which
-// carries `id`/`sqlExecutionId` but not this file's fuller `DetectorStage`
-// shape.
+// Shared by every scope:'sql' detector. sql.get(id).stageIds is always empty (parser-worker
+// never populates it), so stage linkage is derived from each stage's own sqlExecutionId.
+// Minimal param shape (not DetectorStage): external callers pass Map<StageId, Stage>.
 export function stageIdsForSqlExec(
   executionId        ,
   stages                                                             ,
@@ -213,38 +195,23 @@ export function stageIdsForSqlExec(
   return out;
 }
 
-// Shared by the three Plan Advisor detectors below (duplicatePlanSubtree,
-// smallFiles, broadcastSizing): union the given nodes' own `stageIds`, or
-// fall back to the whole execution's stage set when none of them have any
-// coverage. A finding never partially blends a narrowed set with the
-// execution-wide one (see docs/architecture.md's plan-node-to-stage mapping
-// section). `fallback` is a param, not computed here, so callers can compute
-// `stageIdsForSqlExec` once per `detect()` call and reuse it across every
-// finding in that call instead of re-walking `stages` per finding.
+// Shared by the three Plan Advisor detectors: union the given nodes' own stageIds, or fall back
+// to the whole execution's stage set when none have coverage (never a partial blend). `fallback`
+// is a param so callers compute stageIdsForSqlExec once per detect() and reuse it per finding.
 export function unionStageIds(nodes            , fallback          )           {
   const union = new Set        ();
   for (const node of nodes) for (const sid of node.stageIds ?? []) union.add(sid);
   return union.size > 0 ? [...union].sort((a, b) => a - b) : fallback;
 }
 
-// Bottom-up shape computation for duplicate-subtree detection (sparkDoctor
-// idea, src/detectors.js `duplicatePlanSubtree`) and for the cachingOpportunity
-// composite (join/union) detector's anchor-fingerprint contract. `size` is the
-// node count of the subtree rooted at each node; the default fingerprint
-// encodes operator name + sorted metric *names* (never values, per spec) +
-// children fingerprints in original order, so two subtrees with the same shape
-// but different row counts/literals still collide, which is the point (we
-// have no expr/plan/codegen IDs to strip in the first place, since `metrics`
-// never carried them).
+// Bottom-up shape computation for duplicate-subtree detection and the
+// cachingOpportunity composite detector. `size` is the subtree node count; the default
+// fingerprint encodes operator name + sorted metric NAMES (never values, per spec) + child
+// fingerprints, so two subtrees with the same shape but different values still collide.
 //
-// `opts.includeDetail` (default false) folds `root`'s own `detail` text
-// (normalized via `opts.normalizeDetail`) into ONLY `root`'s fingerprint,
-// never into any recursive child call's fingerprint, regardless of `opts`.
-// This is what lets a caller ask "does this specific node's own detail +
-// structural shape match another node's", without descendant filter/scan
-// detail (literals, paths) ever entering the comparison. The existing
-// `duplicatePlanSubtree` call site passes no options: identical behavior,
-// zero regression to its existing tests.
+// opts.includeDetail (default false) folds root's own detail (via opts.normalizeDetail) into
+// ONLY root's fingerprint, never a child's: lets a caller match "this node's own detail + shape"
+// without descendant scan detail entering the comparison.
                                                           
 
 export function computePlanShapes(
@@ -256,9 +223,22 @@ export function computePlanShapes(
   const allNodes             = [];
   function visit(node          , isRoot         )            {
     allNodes.push(node);
-    const childShapes = (node.children ?? []).map((c) => visit(c, false));
+    // A read half wrapping a write half (the Exchange split from
+    // resolvePlanTree, see event-handlers.ts) is one logical Spark operator
+    // for subtree-shape purposes. Without this, every real Exchange in a
+    // matched subtree would count twice, inflating duplicatePlanSubtree's
+    // reported subtreeSize and shifting its groupIndex-derived findingIds
+    // for an otherwise-unchanged plan. Skip straight through the write
+    // wrapper: size comes from its real children, and metricNames from its
+    // real metrics (the read half's own metrics are always empty), so
+    // fingerprint distinctiveness between different real Exchanges is
+    // preserved too.
+    const writeHalf = node.exchangeRole === 'read' ? node.children[0] : null;
+    const realChildren = writeHalf ? writeHalf.children : (node.children ?? []);
+    const realMetrics = writeHalf ? writeHalf.metrics : node.metrics;
+    const childShapes = realChildren.map((c) => visit(c, false));
     const size = 1 + childShapes.reduce((sum, c) => sum + c.size, 0);
-    const metricNames = (node.metrics ?? []).map((m) => m.name).sort().join(',');
+    const metricNames = (realMetrics ?? []).map((m) => m.name).sort().join(',');
     const childFingerprints = childShapes.map((c) => c.fingerprint).join(',');
     const fingerprint = isRoot && includeDetail
       ? `${node.name}[${metricNames}]<${normalize(node.detail ?? '')}>{${childFingerprints}}`
@@ -271,16 +251,10 @@ export function computePlanShapes(
   return { shapeOf, allNodes };
 }
 
-// Normalizes an anchor join/union node's own `detail` text for the
-// cachingOpportunity composite detector's structural fingerprint
-// (computePlanShapes's opts.includeDetail path). Strips per-analysis
-// numbering noise that is never part of a join/union's logical identity:
-// expr ids, plan/codegen-stage ids, and AQE's runtime BuildLeft/BuildRight
-// broadcast-side choice (which can flip between executions of the logically
-// identical join based on runtime stats); it then canonicalizes commutative
-// equality operand order so `A.x = B.y` and `B.y = A.x` collide. Everything
-// else (join type, columns, literal values) is kept: that's the
-// semantically meaningful part a leaf-relation-set identity would miss.
+// Normalizes an anchor join/union node's detail for the cachingOpportunity composite
+// fingerprint. Strips per-analysis numbering (expr ids, plan/codegen ids) and AQE's runtime
+// BuildLeft/BuildRight choice (can flip between runs), then canonicalizes commutative equality
+// operand order so `A.x = B.y` and `B.y = A.x` collide. Join type, columns, literals are kept.
 export function normalizeDetail(detail        )         {
   let s = detail
     .replace(/#\d+L?/g, '')
@@ -296,34 +270,21 @@ export function normalizeDetail(detail        )         {
 
 const JOIN_NAME_RE = /Join/i;
 
-// Structural operator kind for cachingOpportunity's composite detection:
-// 'join' covers every Spark join physical operator (SortMergeJoin,
-// BroadcastHashJoin, ShuffledHashJoin, BroadcastNestedLoopJoin, the same set
-// plan-summary.js's visitJoin recognizes); 'union' is Spark's exact `Union`
-// node name. CartesianProduct is deliberately excluded (out of scope, same
-// as plan-summary.js's join handling).
+// Structural operator kind for cachingOpportunity's composite detection: 'join' covers every
+// Spark join physical operator; 'union' is Spark's exact `Union` node. CartesianProduct is
+// deliberately excluded (out of scope, as in plan-summary.ts).
 export function planOperatorKind(name        )                          {
   if (JOIN_NAME_RE.test(name)) return 'join';
   if (name === 'Union') return 'union';
   return null;
 }
 
-// Single bottom-up pass over a resolved planTree producing one composite
-// candidate per join/union node, in O(n) total (see the design doc's
-// "Compute cost" section; this deliberately does NOT call
-// computePlanShapes per join/union node, since subtrees overlap and that
-// would be O(n·k) on multi-way star/snowflake joins). For every node it
-// computes the plain (detail-free) fingerprint once (identical formula to
-// computePlanShapes's default path) and merges each subtree's leaf-relation
-// byte map (via scanRelationId, same identity cachingOpportunity's existing
-// leaf aggregation uses) bottom-up. When a node is a join/union, its anchor
-// fingerprint folds only its OWN normalized detail (per computePlanShapes's
-// opts.includeDetail contract), computed here inline, in O(1), from the
-// node's own detail plus its already-computed child fingerprints, not via a
-// nested computePlanShapes call. `ancestorNodes` (strict ancestors, root
-// first) is threaded down for free via the recursion's own call stack, so
-// later nested-composite dedupe (cachingOpportunity.detect()) doesn't need a
-// separate tree walk to determine containment.
+// Single bottom-up O(n) pass producing one composite candidate per join/union node. Deliberately
+// does NOT call computePlanShapes per node (subtrees overlap, that would be O(n·k) on
+// star/snowflake joins): computes the plain fingerprint once and merges each subtree's
+// leaf-relation byte map bottom-up. A join/union's anchor fingerprint folds only its OWN
+// normalized detail, inline in O(1). `ancestorNodes` threads down via the call stack so
+// nested-composite dedupe needs no separate tree walk.
                                      
                  
                              
@@ -374,17 +335,10 @@ export function findCompositeCandidates(root          )                       {
 }
 
 
-// First scanned table/relation identity found in a subtree (pre-order, per
-// walkPlanTree's contract), or null when the subtree touches no named
-// relation. Surfaced on duplicatePlanSubtree findings (as `sampleRelation`,
-// see findDuplicateSubtrees below) so a user can tell apart two same-shaped
-// duplicate groups that scan different tables (real-log bug: two unrelated
-// "BroadcastExchange over a Project/Filter/Scan" patterns, one per dimension
-// table, produced byte-identical findings). This is best-effort/informational
-// only, not a uniqueness guarantee: it's null for scan-less subtrees (JDBC/
-// Kafka/LocalRelation) and can coincide when two groups share their first-
-// encountered leaf. See findDuplicateSubtrees's groupIndex for the actual
-// discriminator findingId() relies on.
+// First scanned relation identity in a subtree (pre-order), or null when none. Surfaced on
+// duplicatePlanSubtree findings as `sampleRelation` so a user can tell apart same-shaped groups
+// that scan different tables. Best-effort only: null for scan-less subtrees, can coincide across
+// groups; findDuplicateSubtrees's groupIndex is the actual discriminator findingId relies on.
 function firstLeafRelationId(node          )                {
   let found                = null;
   walkPlanTree(node, (n) => {
@@ -394,14 +348,10 @@ function firstLeafRelationId(node          )                {
   return found;
 }
 
-// Groups nodes by fingerprint, keeping only groups of size >= minOccurrences
-// whose shared subtree size is >= minSubtreeSize. De-overlap: processes
-// candidate groups largest-subtree-first, and once a group is accepted every
-// node inside each of its matched occurrences is marked "claimed" so a
-// smaller, fully-nested duplicate group inside an already-accepted match is
-// dropped (a 5-node duplicate should not also emit findings for its 3-node
-// sub-subtrees); occurrences of a smaller group that fall OUTSIDE any
-// accepted larger match still count normally.
+// Groups nodes by fingerprint, keeping groups of size >= minOccurrences whose subtree size is
+// >= minSubtreeSize. De-overlap: process largest-subtree-first, and once a group is accepted mark
+// every node in its matches "claimed" so a smaller fully-nested duplicate is dropped; occurrences
+// of a smaller group OUTSIDE any accepted match still count.
                                  
                    
                       
@@ -417,7 +367,12 @@ export function findDuplicateSubtrees(
   { minSubtreeSize, minOccurrences }                                                    ,
 )                          {
   const { shapeOf, allNodes } = computePlanShapes(root);
-  const eligible = allNodes.filter(n => shapeOf.get(n) .size >= minSubtreeSize);
+  // Defensive, not load-bearing: computePlanShapes's visit() already skips
+  // straight through a read node to its write half's real children, so no
+  // write-half node is ever pushed into allNodes in the first place, this
+  // filter can structurally never exclude anything. Kept in case that
+  // invariant ever changes upstream.
+  const eligible = allNodes.filter(n => shapeOf.get(n) .size >= minSubtreeSize && n.exchangeRole !== 'write');
 
   const groups = new Map                    ();
   for (const n of eligible) {
@@ -445,14 +400,10 @@ export function findDuplicateSubtrees(
       rootName: unclaimed[0].name,
       subtreeSize: shapeOf.get(unclaimed[0]) .size,
       occurrences: unclaimed.length,
-      isExchangeRoot: /Exchange/i.test(unclaimed[0].name),
+      isExchangeRoot: isExchangeNode(unclaimed[0]),
       sampleRelation: firstLeafRelationId(unclaimed[0]),
-      // Deterministic position within this execution's group list. `sampleRelation`
-      // is best-effort (null when the subtree touches no named catalog relation, e.g.
-      // JDBC/Kafka/LocalRelation sources, or identical when two groups happen to share
-      // their first-encountered leaf) and is NOT sufficient on its own to guarantee two
-      // structurally-distinct groups get distinct finding ids; groupIndex is the actual
-      // uniqueness guarantee findingId() relies on.
+      // Deterministic position within this execution's group list: the actual uniqueness
+      // guarantee findingId relies on, since sampleRelation is best-effort (null or coincident).
       groupIndex: results.length,
       nodes: unclaimed,
     });
@@ -460,21 +411,16 @@ export function findDuplicateSubtrees(
   return results;
 }
 
-// Exact metric names Spark emits: verified against a real SQLExecutionStart
-// event's sparkPlanInfo in examples/big-application_1777489669889_51251_1.
-// NOTE: the write-side byte metric is "written output", not "size of written
-// files" as an earlier draft of this detector's spec assumed.
+// Exact metric names Spark emits, verified against a real SQLExecutionStart's sparkPlanInfo.
+// The write-side byte metric is "written output", not "size of written files".
 const FILES_READ_COUNT = 'number of files read';
 const FILES_READ_BYTES = 'size of files read';
 const FILES_WRITTEN_COUNT = 'number of written files';
 const FILES_WRITTEN_BYTES = 'written output';
 
-// Byte size of a join-side subtree for broadcast sizing (dataflint
-// JoinToBroadcastAlert). Stops descending the instant a node carries a
-// "data size" metric: that node's value already aggregates everything
-// beneath it (e.g. an Exchange's "data size" already reflects everything it
-// shuffled), so summing further down would double-count. Only recurses into
-// children when the current node carries no such metric.
+// Byte size of a join-side subtree for broadcast sizing. Stops
+// descending at a node with a "data size" metric: that value already aggregates everything
+// beneath it, so summing further would double-count. Only recurses when no such metric.
 function sumBoundarySize(node          )         {
   const m = (node.metrics ?? []).find(x => x.name === 'data size');
   if (m) return m.value;
@@ -483,10 +429,8 @@ function sumBoundarySize(node          )         {
   return sum;
 }
 
-// Nodes that actually fed sumBoundarySize's total for this subtree: mirrors
-// its recursion exactly (same "data size" metric check, same stop condition)
-// so the implicated stageIds line up with the size that was actually
-// compared, however deep that turns out to live.
+// Nodes that fed sumBoundarySize's total: mirrors its recursion exactly so implicated stageIds
+// line up with the size actually compared.
 function boundarySizeContributors(node          )             {
   const m = (node.metrics ?? []).find((x) => x.name === 'data size');
   if (m) return [node];
@@ -516,10 +460,8 @@ function maxMedianRatio(
                      
  
 
-// Machine-readable detector metadata for the evidence report: type, version,
-// scope, thresholds, and doc anchor per entry (no `detect` closure). Lets a
-// portable report record exactly which detector + threshold set produced each
-// finding, so evidence stays reproducible as detectors evolve.
+// Machine-readable detector metadata for the evidence report (no `detect` closure), so a
+// portable report records which detector + thresholds produced each finding.
 export function detectorCatalog()                         {
   return DETECTORS.map((d) => ({
     type: d.type,
@@ -530,21 +472,11 @@ export function detectorCatalog()                         {
   }));
 }
 
-// True task-duration skew ratio for a stage: P95/median once there are enough
-// tasks to trust a P95 estimate, otherwise max/median. Returns null when the
-// stage has no measurable median (p50 === 0). Exported so the CLI budget gate
-// (src/cli/budgets.ts) can recompute the same ratio the detector uses, rather
-// than reading the detector's own findings (which are floored at ratioWarn).
-//
-// Fields widened to optional: the `skew` detector below only ever calls this
-// with an already-finalized `DetectorStage` (all four always numeric by the
-// time `analyze()` runs), but `cli/budgets.ts`'s `checkSkew` calls it
-// directly against `AppModel.stages`: real `Stage` records for a stage that
-// never received a `StageCompleted` event (e.g. an unfinished run) genuinely
-// lack these fields (see `types.ts`'s `Stage`). The `as number` casts below
-// preserve the original behavior byte-for-byte: dividing through an absent
-// field still naturally produces `NaN` (as it always has for untyped JS
-// callers), rather than adding a new guard that would change the result.
+// True task-duration skew ratio: P95/median once enough tasks to trust P95, else max/median.
+// Null when no measurable median (p50 === 0). Exported so cli/budgets.ts recomputes the same
+// ratio rather than reading findings floored at ratioWarn.
+// Fields optional: budgets.ts calls this against raw AppModel.stages, whose stages may lack
+// these fields (unfinished run). The `as number` casts keep behavior: an absent field yields NaN.
 export function computeSkewRatio(
   stage                                                                                                      ,
   minTasksForP95        ,
@@ -556,18 +488,10 @@ export function computeSkewRatio(
     : { ratio: (max          ) / (p50          ), metric: 'max/median' };
 }
 
-// Absolute-magnitude floor expressed as a % of total app runtime rather than
-// a fixed ms constant (mirrors computeSpillMagnitude's/slowHost's ratio+floor
-// pattern above/below): a skew/straggler/taskStageSkew ratio computed on a
-// handful of milliseconds is noise in a run that took hours, but the same
-// absolute waste is real in a run that only took seconds; a fixed-ms floor
-// can't scale between those. Used by the `skew` and `straggler` entries
-// below, each gated via `clippedWasteMs` (below) against the *same
-// occupancy-clipped* wall-clock figure
-// src/impact-estimator.ts displays as that finding's savings, not the raw
-// pre-clip delta, which can stay large after clipping collapses the
-// recoverable time to near zero (the stage's own longest task already
-// accounts for nearly all of its wall-clock window).
+// Absolute-magnitude floor as a % of app runtime, not a fixed ms constant: a skew/straggler
+// ratio on a few ms is noise in an hours-long run but real in a seconds-long one; a fixed-ms
+// floor can't scale. Used by skew/straggler, gated via clippedWasteMs against the same
+// occupancy-clipped figure impact-estimator.ts displays as savings.
 // NOT SOURCED: floor percentages are our own noise floor, unvalidated.
 function computeAppDurationMs(ctx              )                {
   const app = ctx?.app;
@@ -576,34 +500,22 @@ function computeAppDurationMs(ctx              )                {
   return durationMs > 0 ? durationMs : null;
 }
 
-// Unknown app timing (computeAppDurationMs returned null) never suppresses a
-// finding; it just skips the floor gate, preserving prior ratio-only
-// behavior when total runtime can't be computed.
+// Unknown app timing never suppresses a finding; it just skips the floor gate.
 function meetsRuntimeFloor(wasteMs        , appDurationMs               , floorPct        )          {
   return appDurationMs == null || wasteMs >= appDurationMs * floorPct;
 }
 
-// Runs a raw waste delta through the same ceiling/occupancy clip
-// src/impact-estimator.ts's singleStageImpact applies before display, so the
-// runtime floor above is checked against a stage's actual recoverable
-// wall-clock time rather than a delta that a physical floor (the stage's own
-// longest task) may leave almost entirely unrecoverable. Falls back to the
-// raw delta when occupancy data isn't available for this stage (ctx omitted,
-// or the stage was excluded from the occupancy sweep for having <= 0
-// duration), same as the pre-existing ratio-only behavior for unknown app
-// timing above.
+// Runs a raw waste delta through the same occupancy clip impact-estimator.ts applies before
+// display, so the runtime floor checks recoverable wall-clock, not a delta a physical floor
+// leaves unrecoverable. Falls back to the raw delta when occupancy data is unavailable.
 function clippedWasteMs(wasteMs        , stageId        , ctx              )         {
   if (!ctx) return wasteMs;
   const est = estimateSingleStage(wasteMs, stageId, ctx.stages                                          , ctx.occupancy);
   return est ? est.wallClock.high : wasteMs;
 }
 
-// cacheUtilization's per-RDD copy (private to this file), following the
-// existing pattern of small per-detector formatting helpers (e.g.
-// pickDominantReason above). Both variants share the same confidence/
-// validationRequired text: the ratio is a point-in-time storage snapshot
-// from stage-submission events (src/event-handlers.js's mergeStageRddInfo),
-// not a runtime block-access read-count.
+// Shared by cacheUtilization's two variants: the ratio is a point-in-time storage snapshot from
+// stage-submission events, not a runtime block-access read-count.
 const CACHE_UTILIZATION_VALIDATION =
   "This ratio is a point-in-time storage snapshot from stage-submission events, not a runtime read-count. Confirm against the Spark UI's Storage tab before acting.";
 
@@ -638,19 +550,11 @@ function diskSpilloverFinding(rdd                 , diskRatio        , impactBan
   };
 }
 
-// Entry shape for every item in DETECTORS. `TTarget` stays `unknown` at the
-// array level (kept as the default, never instantiated per-scope): `detect`'s
-// real first-argument shape varies by `scope` (a `DetectorStage` for
-// 'stage', a `DetectorSqlExec` for 'sql', a `DetectorCtx` for 'app', or a
-// narrower `{ app }` for 'config'; see analyzer.js's `analyze`/`auditConfig`,
-// the only real callers), and unifying those four into one `TTarget` would
-// need either an unsound cast or a discriminated-union-of-detectors redesign
-// this migration task doesn't ask for. Each entry below still gets a
-// precisely-typed `detect` by annotating its own `target`/`ctx` parameters
-// directly: object-literal methods (this `detect(target) {}` shorthand, not
-// an arrow function assigned to a property) are checked bivariantly against
-// an interface's method parameter types, so a narrower, concrete annotation
-// here does not conflict with `Detector`'s `unknown` declaration.
+// Entry shape for every DETECTORS item. TTarget stays `unknown` at the array level: detect's
+// real first-arg varies by scope (DetectorStage/DetectorSqlExec/DetectorCtx/{ app }), and
+// unifying them would need an unsound cast or a discriminated-union redesign. Each entry gets a
+// precise detect by annotating its own params: object-literal method params are checked
+// bivariantly, so a narrower annotation here doesn't conflict with the `unknown` declaration.
                                               
                
                                             
@@ -658,14 +562,11 @@ function diskSpilloverFinding(rdd                 , diskRatio        , impactBan
                        
                   
                      
-                                                                           
-                                                                            
-                                                                             
-                                                                        
-                    
+                                                                                             
                                                  
                           
                       
+                              
                         
                     
                                                                
@@ -678,9 +579,8 @@ function diskSpilloverFinding(rdd                 , diskRatio        , impactBan
 // *Ratio = multiplicative factor
 // *Share/*Rate/*Util = 0–1 fraction (normalized)
 
-// `straggler`'s own noise-floor thresholds (NOT SOURCED: unvalidated),
-// exported so src/impact-band.ts can reuse the same figures as its global
-// impact-band floor instead of hand-copying the literals.
+// straggler's noise-floor thresholds (NOT SOURCED: unvalidated), exported so impact-band.ts
+// reuses the same figures instead of hand-copying.
 export const STRAGGLER_FLOOR_PCT_WARN = 0.005;
 export const STRAGGLER_FLOOR_PCT_CRIT = 0.02;
 
@@ -700,9 +600,8 @@ export const DETECTORS             = [
       if (result === null) return null;
       const { ratio, metric } = result;
       if (ratio <= this.thresholds.ratioWarn) return null;
-      // Same absolute delta src/impact-estimator.ts's 'skew' case reports as
-      // this finding's savings; clipped the same way before the floor check
-      // so the gate agrees with what's actually displayed.
+      // Same absolute delta impact-estimator.ts's 'skew' case reports as savings; clipped the
+      // same way before the floor check so the gate agrees with what's displayed.
       const wasteMs = Math.max(0, metric === 'P95/median' ? stage.taskDurationP95 - stage.taskDurationP50 : stage.taskDurationMax - stage.taskDurationP50);
       const appDurationMs = computeAppDurationMs(ctx);
       const floorWasteMs = clippedWasteMs(wasteMs, stage.id, ctx);
@@ -712,6 +611,8 @@ export const DETECTORS             = [
         type: 'skew', stageId: stage.id,
         impactBand: 'warning',
         metric, value,
+        confidence: 'low',
+        validationRequired: 'The 0.5% runtime-floor percentage that gates this finding is our own noise floor, unvalidated: no external tool publishes an equivalent metric to calibrate against. Confirm against known-good/known-bad real logs before trusting the impact-band split.',
         recommendation: `Task duration ratio (${metric}) is ${value}×: for join-driven skew, enable AQE skew-join handling (spark.sql.adaptive.skewJoin.enabled); otherwise salt the key or repartition on a better key to reduce task skew.`,
       };
     },
@@ -753,11 +654,9 @@ export const DETECTORS             = [
           });
         }
       }
-      // TaskStageSkew: straggler cost vs stage wall-clock. Skip near-zero duration.
-      // Always info, like its lowParallelism/dataExplosion siblings above: satisfying
-      // this trigger mathematically forces the occupancy-clipped wall-clock estimate to
-      // exactly zero on every firing (see impact-estimator.ts's costOnly branch below),
-      // so there is no wall-clock-backed impact-band tier left to gate on.
+      // TaskStageSkew: straggler cost vs stage wall-clock. Skip near-zero duration. Always info
+      // like its siblings: this trigger forces the occupancy-clipped estimate to exactly zero on
+      // every firing, so there's no wall-clock-backed tier left to gate on.
       const stageDurationMs = (stage.completedAt ?? 0) - (stage.submittedAt ?? 0);
       if (stageDurationMs > 0) {
         const ratio = stage.taskDurationMax / stageDurationMs;
@@ -808,9 +707,8 @@ export const DETECTORS             = [
       const out            = [];
       const { shuffleReadP50: p50, shuffleReadMax: max, shuffleReadBytes: total, taskCount } = stage;
       if (max > this.thresholds.skewRatio * p50 && max > this.thresholds.skewFloorBytes) {
-        // p50 can be 0 (more than half the shuffle partitions empty): a
-        // ratio against zero renders the literal string "Infinity×", so fall
-        // back to median-free phrasing instead of dividing by p50.
+        // p50 can be 0 (over half the shuffle partitions empty): a ratio against zero renders
+        // "Infinity×", so fall back to median-free phrasing.
         const ratioText = p50 > 0
           ? `${Math.round(max / p50 * 10) / 10}× the median (${formatBytes(p50)})`
           : `far larger than the median (${formatBytes(p50)}, effectively empty)`;
@@ -828,6 +726,10 @@ export const DETECTORS             = [
         });
       }
       if (max >= this.thresholds.maxPartBytes) {
+        // Fixed 'critical': an OOM/crash-risk safety signal, not a time-waste one. Exempted in
+        // impact-band.ts's deriveImpactBand from the wall-clock-based overwrite every other
+        // finding here gets, so a long-running job can't demote an active crash risk to 'info'
+        // just because the modeled time savings are a small fraction of total runtime.
         out.push({
           type: 'partitionSizing', stageId: stage.id, impactBand: 'critical',
           rule: 'maxPartitionTooBig', metric: 'shuffleReadMax', value: max,
@@ -864,18 +766,19 @@ export const DETECTORS             = [
   {
     type: 'gc', scope: 'stage', order: 50, fixEffort: 'config', version: 1,
     docAnchor: '#bottleneck-gc',
+    confidence: 'low',
+    validationRequired: 'The 10-second minimum-runtime floor that gates this finding is our own noise floor, unvalidated: no external tool publishes an equivalent metric to calibrate against. Confirm against known-good/known-bad real logs before trusting the impact-band split.',
     thresholds: {
       warnPct100: 10,
-      // Descending tier: Dr. Elephant ExecutorGcHeuristic, ported as-is.
+      // Descending tier: ExecutorGcHeuristic, ported as-is.
       lowInfoPct100: 5,
-      // NOT SOURCED: our own noise floor so a stage that barely ran (gcPct
-      // near 0 or wildly inflated by a tiny denominator) does not flag,
-      // in either direction.
+      // NOT SOURCED: our own noise floor so a stage that barely ran doesn't flag either direction.
       minRunTimeMs: 10000,
     },
     detect(
              
                                                                                         
+                                                       
         
       stage               ,
     )                 {
@@ -887,6 +790,7 @@ export const DETECTORS             = [
           type: 'gc', stageId: stage.id,
           impactBand: 'warning',
           metric: 'gcPct', value,
+          confidence: this.confidence, validationRequired: this.validationRequired,
           recommendation: `GC consumed ${value}% of executor run time: reduce object creation, use primitive types, avoid UDFs, increase executor memory.`,
         };
       }
@@ -898,6 +802,7 @@ export const DETECTORS             = [
           type: 'gc', stageId: stage.id, direction: 'low',
           impactBand: 'info',
           metric: 'gcPct', value,
+          confidence: this.confidence, validationRequired: this.validationRequired,
           recommendation: `GC consumed only ${value}% of executor run time: memory may be over-provisioned; consider reducing spark.executor.memory for cost savings.`,
         };
       }
@@ -909,12 +814,9 @@ export const DETECTORS             = [
     docAnchor: '#bottleneck-slow-host',
     thresholds: {
       minHosts: 3, minTasks: 15, ratioWarn: 2.0, minShare: 0.20, shareWarn: 0.75, taskShareWarn: 0.50, ratioTiers: [1.33, 1.78, 3.16, 10],
-      // Absolute-magnitude floors (mirrors computeSpillMagnitude's ratio+floor
-      // pattern): on short stages, sub-second/sub-64MB differences between
-      // hosts or executors produce huge ratios that are pure noise, not a
-      // real slow-host problem. 1s is well above typical per-task scheduling
-      // jitter but well below the tens-of-seconds+ means genuine slow-host
-      // stages exhibit; 64MB mirrors the spill detector's disk-skew floor.
+      // Absolute-magnitude floors (mirrors computeSpillMagnitude's ratio+floor pattern): on short
+      // stages, sub-second/sub-64MB host differences produce huge noise ratios. 1s is above
+      // per-task jitter but below genuine slow-host stages; 64MB mirrors the spill disk-skew floor.
       floorMs: 1000, floorBytes: 64 * MB,
     },
     detect(
@@ -946,7 +848,7 @@ export const DETECTORS             = [
               // `value` is a ratio; the estimator needs the absolute per-host mean.
               hostMeanMs: h.mean,
               host: h.host, hostTaskShare: Math.round(share * 100) / 100,
-              recommendation: `Check executor logs for ${h.host}: possible bad node, disk pressure, or NUMA misalignment.`,
+              recommendation: `${h.host} may just hold data locality for its tasks or carry one heavy stage, not necessarily a hardware fault: check what it was running, and consider enabling spark.speculation to relaunch a lagging task automatically.`,
             });
           }
         }
@@ -1012,10 +914,8 @@ export const DETECTORS             = [
     type: 'stageSlowness', scope: 'stage', order: 65, fixEffort: 'code', version: 2,
     docAnchor: '#bottleneck-stage-slowness',
     thresholds: { infoMin: 15 },
-    // Cross-detector suppression (new pattern; see "Detector contract" in
-    // docs-site/contributor-guide/architecture/detector-contract.md).
-    // Requires this entry to be declared AFTER slowHost in DETECTORS so
-    // slowHost findings are already in `out`.
+    // Cross-detector suppression (see "Detector contract" in detector-contract.md). Requires this
+    // entry to be declared AFTER slowHost in DETECTORS so slowHost findings are already in `out`.
     suppressWhen(finding, out) {
       return out.some(o => o.type === 'slowHost' && o.stageId === finding.stageId);
     },
@@ -1023,9 +923,8 @@ export const DETECTORS             = [
                                                 
       stage               ,
     )                 {
-      // Basis is real wall-clock stage duration, not per-executor average
-      // (Decision 7); Task 11's impact-estimator formula reuses this exact
-      // stageDurationMs computation.
+      // Basis is real wall-clock stage duration, not per-executor average; the impact-estimator
+      // formula reuses this exact stageDurationMs computation.
       const stageDurationMs = (stage.completedAt ?? 0) - (stage.submittedAt ?? 0);
       if (!(stageDurationMs > 0)) return null;
       const durationMinutes = stageDurationMs / 60000;
@@ -1036,7 +935,7 @@ export const DETECTORS             = [
       return {
         type: 'stageSlowness', stageId: stage.id, impactBand,
         metric: 'stageDurationMinutes', value,
-        recommendation: `This stage ran ${value} minutes with no more specific cause flagged: profile its query plan and check for wide shuffles or expensive UDFs.`,
+        recommendation: `This stage ran ${value} minutes with no more specific cause flagged: often a partition-count problem, raise parallelism via spark.sql.shuffle.partitions or spark.default.parallelism, or check for a large per-task data volume driving heavy shuffle and spill.`,
       };
     },
   },
@@ -1050,6 +949,9 @@ export const DETECTORS             = [
         type: 'stageFailed', stageId: stage.id, impactBand: 'critical',
         variant: 'stageFailure',
         metric: 'stageFailureReason', value: stage.stageFailureReason,
+        numTasks: stage.taskCount,
+        memoryBytesSpilled: stage.memoryBytesSpilled,
+        failedTaskDetails: stage.failedTaskSamples ?? [],
         recommendation: `This stage attempt failed outright. Inspect the driver log for the failure reason and the job that triggered it.`,
       };
     },
@@ -1081,9 +983,8 @@ export const DETECTORS             = [
   {
     type: 'straggler', scope: 'stage', order: 70, fixEffort: 'code', version: 1,
     docAnchor: '#bottleneck-straggler',
-    // floorPctWarn/floorPctCrit are re-exported as STRAGGLER_FLOOR_PCT_WARN/CRIT
-    // below and reused as src/impact-band.ts's global noise floor: keep the two
-    // in sync, don't hand-edit one without the other.
+    // floorPctWarn/floorPctCrit are re-exported as STRAGGLER_FLOOR_PCT_WARN/CRIT and reused as
+    // impact-band.ts's global noise floor: keep the two in sync.
     thresholds: { minTasks: 10, shareWarn: 0.05, warnPct: 0.10, critPct: 0.20, floorPctWarn: STRAGGLER_FLOOR_PCT_WARN, floorPctCrit: STRAGGLER_FLOOR_PCT_CRIT },
     detect(
              
@@ -1097,12 +998,9 @@ export const DETECTORS             = [
       if ((stage.speculativeTasks ?? 0) === 0 && stragglerShare <= this.thresholds.shareWarn) return null;
       const useSpeculative = (stage.speculativeTasks ?? 0) > 0;
       const speculativeShare = useSpeculative ? stage.speculativeTasks / stage.taskCount : 0;
-      // Same absolute delta src/impact-estimator.ts's shared straggler/
-      // stageShape case reports as this finding's savings: a high share of
-      // stragglers/speculative retries on a stage whose tasks barely vary in
-      // duration models near-zero savings, so it must not outrank 'info'.
-      // Clipped the same way before the floor check so the gate agrees with
-      // what's actually displayed.
+      // Same absolute delta impact-estimator.ts's straggler/stageShape case reports as savings: a
+      // high straggler/speculative share on a stage whose tasks barely vary models near-zero
+      // savings, so it must not outrank 'info'. Clipped the same way before the floor check.
       const wasteMs = Math.max(0, stage.taskDurationMax - stage.taskDurationP50);
       const appDurationMs = computeAppDurationMs(ctx);
       const floorWasteMs = clippedWasteMs(wasteMs, stage.id, ctx);
@@ -1110,21 +1008,14 @@ export const DETECTORS             = [
       const meetsCritFloor = meetsRuntimeFloor(floorWasteMs, appDurationMs, this.thresholds.floorPctCrit);
       const speculativeTier = speculativeShare >= this.thresholds.critPct && meetsCritFloor ? 'critical'
                              : speculativeShare >= this.thresholds.warnPct && meetsWarnFloor ? 'warning' : 'info';
-      // Straggler share has no dedicated critical tier per
-      // docs-site/contributor-guide/architecture/detector-contract.md; it can only push to warning.
+      // Straggler share has no dedicated critical tier per detector-contract.md; only warning.
       const stragglerTier = stragglerShare > this.thresholds.shareWarn && meetsWarnFloor ? 'warning' : 'info';
-      // Fixed fallback: overwritten by deriveImpactBand (src/impact-band.ts) whenever
-      // this finding gets a real wallClock estimate, which is the common case. Only
-      // surfaces on the rare miss (stage excluded from the occupancy sweep).
+      // Fixed fallback: overwritten by deriveImpactBand when this finding gets a real wallClock
+      // estimate (the common case). Only surfaces on the rare occupancy-sweep miss.
       const impactBand = 'info';
-      // Report whichever signal actually drove the finding, not just whether
-      // speculative execution happened to be on: a high stragglerShare with
-      // few/no speculative retries must not be reported as a low-value
-      // speculativeTasks count (real-log bug: a 50%-straggler-share stage
-      // with 1 speculative task reported an impact band of 'warning' but metric
-      // 'speculativeTasks: 1', hiding the actual cause). Ties keep the prior
-      // default (speculative-driven) so existing speculative-only findings
-      // are unaffected.
+      // Report whichever signal actually drove the finding, not just whether speculation was on:
+      // a high stragglerShare with few speculative retries must not be reported as a low-value
+      // speculativeTasks count. Ties keep the speculative-driven default.
       const useSpeculativeMetric = useSpeculative && !(IMPACT_BAND_ORDER[stragglerTier] < IMPACT_BAND_ORDER[speculativeTier]);
       const value = useSpeculativeMetric ? stage.speculativeTasks : Math.round(stragglerShare * 100);
       const detail = useSpeculativeMetric
@@ -1137,7 +1028,9 @@ export const DETECTORS             = [
         unit: useSpeculativeMetric ? 'count' : 'pct',
         speculativeTasks: stage.speculativeTasks ?? 0,
         stragglerCount: stage.stragglerCount ?? 0,
-        recommendation: `${detail}: investigate stragglers, likely candidates for AQE skewJoin or data locality issues.`,
+        confidence: 'low',
+        validationRequired: 'The 0.5%/2% runtime-floor percentages that gate this finding are our own noise floor, unvalidated: no external tool publishes an equivalent metric to calibrate against. Confirm against known-good/known-bad real logs before trusting the impact-band split.',
+        recommendation: `${detail}: rule out a GC pause or a slow shuffle fetch before assuming a hardware issue; if a skewed key is the real cause, that's a candidate for AQE's skew-join handling.`,
       };
     },
   },
@@ -1179,6 +1072,9 @@ export const DETECTORS             = [
         type: 'retryWaste', stageId: stage.id,
         impactBand: 'warning',
         metric: 'retryWasteMs', value: wastedMs,
+        numTasks: stage.taskCount,
+        memoryBytesSpilled: stage.memoryBytesSpilled,
+        retriedTaskDetails: stage.retryTaskSamples ?? [],
         recommendation: `Retried task attempts wasted ${Math.round(wastedMs / 1000)}s of executor time (${wasted} attempt${wasted === 1 ? '' : 's'}) even though the stage completed: investigate executor loss or fetch failures.`,
         extended: `${wasted} task attempts were superseded by a later retry, wasting ${Math.round(wastedMs / 1000)}s of executor time. Common causes: executor loss (OOM-kill, node death) or shuffle FetchFailed forcing a stage-map recompute. Check driver logs for the dominant reason (see the Failures widget) even if the final failure rate looks low; retries hide the true cost.`,
       };
@@ -1206,14 +1102,13 @@ export const DETECTORS             = [
     },
   },
   {
-    // No docAnchor set (documented deviation, like autoscalingChurn above):
-    // the upstream `shuffle-works/spark-tuning-reference` docs repo has no
-    // section for this tool-specific "capture stopped early" signal.
+    // No docAnchor: the upstream spark-tuning-reference docs have no section for this
+    // tool-specific "capture stopped early" signal.
     type: 'incompleteRun', scope: 'app', order: 5, fixEffort: 'code', version: 1,
     thresholds: {},
     recommendation: 'This event log never recorded an ApplicationEnd event: the capture stopped before the run finished (an in-flight job, a rotated-away log, or a cut-short capture). Findings and metrics elsewhere on this board reflect only what was captured up to that point, not the full run.',
     detect(                                  ctx             )                 {
-      if (ctx.app.startTime == null || ctx.app.endTime != null) return null;
+      if (!ctx.app || ctx.app.startTime == null || ctx.app.endTime != null) return null;
       return {
         type: 'incompleteRun', stageId: null, impactBand: 'warning',
         metric: 'applicationEnd', value: 'missing',
@@ -1230,18 +1125,22 @@ export const DETECTORS             = [
       ctx             ,
     )                 {
       const { app, stages } = ctx;
-      if (!app.startTime || stages.size === 0) return null;
+      // Nullish (not falsy) check: a literal startTime:0 must not be treated as "missing".
+      if (!app || app.startTime == null || stages.size === 0) return null;
       let firstTaskLaunch = Infinity;
       for (const stage of stages.values()) {
         if (stage.submittedAt > 0 && stage.submittedAt < firstTaskLaunch) firstTaskLaunch = stage.submittedAt;
       }
+      // No stage ever recorded a submission timestamp: no basis to measure a startup gap against.
+      // Exposed now that a literal app.startTime:0 no longer short-circuits this detector entirely.
+      if (!Number.isFinite(firstTaskLaunch)) return null;
       const gapSeconds = (firstTaskLaunch - app.startTime) / 1000;
       if (gapSeconds <= this.thresholds.gapSeconds) return null;
       const value = Math.round(gapSeconds);
       return {
         type: 'coldStart', stageId: null, impactBand: 'warning',
         metric: 'startupGapSeconds', value,
-        recommendation: `Executor startup took ${value}s: consider pre-warming the cluster or using dynamic allocation.`,
+        recommendation: `The first task waited ${value}s for executors to become available: keep a warm pool of idle executors, or if using dynamic allocation, raise the minimum/initial executor count so it doesn't scale up from zero.`,
       };
     },
   },
@@ -1253,25 +1152,27 @@ export const DETECTORS             = [
                                                 
       ctx             ,
     )                 {
-      const { app, executorsAdded, executorsRemoved } = ctx;
-      if (executorsAdded.length === 0 || !app.startTime || !app.endTime) return null;
+      const { app, executorsAdded, executorsRemoved, runAggregates } = ctx;
+      // Nullish (not falsy) check: a literal startTime:0 must not be treated as "missing".
+      if (!app || executorsAdded.length === 0 || app.startTime == null || app.endTime == null) return null;
       const appDuration = app.endTime - app.startTime;
       if (appDuration <= 0) return null;
-      const peakExecutors = executorsAdded.length;
-      let totalActiveMs = 0;
-      const removed = new Map                ();
-      for (const ev of executorsRemoved) removed.set(ev.executorId, ev.timestamp);
-      for (const ev of executorsAdded) {
-        const addedAt = Math.max(ev.timestamp, app.startTime);
-        const removedAt = removed.has(ev.executorId) ? removed.get(ev.executorId)  : app.endTime;
-        totalActiveMs += Math.max(0, removedAt - addedAt);
-      }
-      const utilization = (totalActiveMs / appDuration) / peakExecutors;
+      // computePeakConcurrentCores (not executorsAdded.length/computeTotalCores): real concurrent
+      // capacity, not a cumulative sum that double-counts a churned-through executor against its
+      // replacement's (spot preemption, dynamicAllocation replacement).
+      const totalCores = computePeakConcurrentCores(app, executorsAdded, executorsRemoved);
+      if (totalCores <= 0) return null;
+      const capacityCoreMs = totalCores * appDuration;
+      // Busy core-time (from the whole-run core-time-series, same signal memoryUtilization's
+      // idleCores variant already uses), not executor lifetime: an executor that exists for the
+      // whole run but sits fully idle must not score as 100% used. Missing runAggregates (older
+      // callers, synthetic fixtures) reads as 0 busy time rather than falling back to the
+      // lifetime-based measure this replaces.
+      const busyCoreMs = runAggregates?.busyCoreMs ?? 0;
+      const utilization = busyCoreMs / capacityCoreMs;
       if (utilization >= this.thresholds.minUtil) return null;
 
       // CPU-time-based utilization (sparkMeasure): metric only, no threshold.
-      // Total cores: prefer executor-added Total Cores (real), else config cores.
-      const totalCores = computeTotalCores(app, executorsAdded);
       let cpuUtilizationPct                = null;
       if (totalCores > 0) {
         let cpuMs = 0;
@@ -1296,10 +1197,10 @@ export const DETECTORS             = [
     type: 'memoryUtilization', scope: 'app', order: 102, fixEffort: 'config', version: 1,
     docAnchor: '#bottleneck-memory-utilization',
     thresholds: {
-      idleCoreWarn: 0.50,          // dataflint WastedCoresAlertsReducer
-      bandTooSmall: 0.95,          // dataflint MemoryAlertsReducer: used/allocated
+      idleCoreWarn: 0.50,          // WastedCoresAlertsReducer
+      bandTooSmall: 0.95,          // MemoryAlertsReducer: used/allocated
       bandTooHigh: 0.70,           // below this => over-provisioned (cost signal)
-      wasteBufferMultiplier: 1.5,  // Dr. Elephant SparkMetricsAggregator: UNVERIFIED
+      wasteBufferMultiplier: 1.5,  // UNVERIFIED
     },
     detect(
              
@@ -1309,19 +1210,20 @@ export const DETECTORS             = [
         
       ctx             ,
     )            {
-      const { app, executorsAdded, runAggregates, stages } = ctx;
+      const { app, executorsAdded, executorsRemoved, runAggregates, stages } = ctx;
       const out            = [];
-      // Nullish (not falsy) check: unlike the older coldStart/utilization
-      // detectors, a literal startTime:0 must not be treated as "missing".
+      // Nullish (not falsy) check: a literal startTime:0 must not be treated as "missing".
       if (app?.startTime == null || app?.endTime == null) return out;
       const appDurationMs = app.endTime - app.startTime;
       if (appDurationMs <= 0) return out;
 
-      // Total cores: prefer real Executor-Added Total Cores, else config.
-      const peakExecutors = executorsAdded.length;
-      const totalCores = computeTotalCores(app, executorsAdded);
-      // Hoisted above 1a (it is also 1b/1c's input) so the idle-cores finding can carry
-      // the allocated memory its MB-seconds impact estimate needs.
+      // Peak concurrent executors/cores (not executorsAdded.length/computeTotalCores): a
+      // cumulative sum or count double-counts a churned-through executor against its replacement's
+      // (spot preemption, dynamicAllocation replacement), inflating idle-rate and waste-model figures.
+      const peakExecutors = computePeakConcurrentExecutorCount(executorsAdded, executorsRemoved);
+      const totalCores = computePeakConcurrentCores(app, executorsAdded, executorsRemoved);
+      // Hoisted above 1a (also 1b/1c's input) so the idle-cores finding carries the allocated
+      // memory its MB-seconds estimate needs.
       const allocatedMB = app.resources?.executor?.memoryMB ?? null;
 
       // ── 1a idle-cores rate ────────────────────────────────────────────────
@@ -1333,8 +1235,7 @@ export const DETECTORS             = [
           out.push({
             type: 'memoryUtilization', variant: 'idleCores', stageId: null,
             impactBand: 'warning', metric: 'idleCoreRate', value,
-            // Raw (unrounded) rate plus the sizing inputs, for the impact estimator's
-            // wasted-MB-seconds model: `value` above is a rounded percentage.
+            // Raw (unrounded) rate plus sizing inputs for the impact estimator: `value` is rounded pct.
             idleRateFraction: idleRate, allocatedMB, peakExecutors, appDurationMs,
             recommendation: `${value}% of allocated core-time ran no task: reduce cluster size or enable dynamic allocation.`,
           });
@@ -1362,10 +1263,8 @@ export const DETECTORS             = [
         const allocatedBytes = allocatedMB * 1024 * 1024;
         for (const [execId, heap] of peakHeapByExec) {
           const ratio = heap / allocatedBytes;
-          // The two bands are opposite signals, not two degrees of one: an explicit
-          // `rule` discriminator (same pattern as stageShape) lets consumers tell the
-          // OOM-risk case from the over-provisioning waste case without re-deriving
-          // the ratio against the thresholds.
+          // The two bands are opposite signals: an explicit `rule` discriminator lets consumers
+          // tell OOM-risk from over-provisioning without re-deriving the ratio.
           if (ratio > this.thresholds.bandTooSmall) {
             out.push({
               type: 'memoryUtilization', variant: 'memoryBand', rule: 'heapNearCapacity',
@@ -1387,7 +1286,7 @@ export const DETECTORS             = [
         }
       }
 
-      // ── 1c Spark Memory Limit waste model (Dr. Elephant, UNVERIFIED buffer) ─
+      // ── 1c Spark Memory Limit waste model (UNVERIFIED buffer) ─
       if (allocatedMB != null && peakExecutors > 0) {
         const allocatedMBSeconds = peakExecutors * allocatedMB * (appDurationMs / 1000);
         let usedRunTimeMs = 0;
@@ -1400,7 +1299,7 @@ export const DETECTORS             = [
             type: 'memoryUtilization', variant: 'wasteModel', stageId: null,
             impactBand: 'info', metric: 'wastedMBSeconds', value,
             confidence: 'low',
-            validationRequired: 'Memory-waste estimate uses allocated-vs-used memory-time and an unverified 1.5x buffer ported from Dr. Elephant: confirm against the Spark UI before acting.',
+            validationRequired: 'Memory-waste estimate uses allocated-vs-used memory-time and an unverified 1.5x buffer: confirm against the Spark UI before acting.',
             recommendation: `Allocated executor memory sat largely idle over the run (~${value.toLocaleString('en-US')} MB-seconds wasted): review spark.executor.memory and executor count.`,
           });
         }
@@ -1410,13 +1309,9 @@ export const DETECTORS             = [
     },
   },
   {
-    // Per-RDD cache-utilization proxies (this repo's own design: Spark
-    // event logs carry no block-access/read-count events, so a literal
-    // cache hit rate isn't derivable; see the design doc for GitHub issue
-    // #85). Two independent, per-RDD tiered checks over `ctx.app.rddInfo`
-    // storage snapshots: partial caching (numCachedPartitions < numPartitions)
-    // and disk spillover (diskSize share of a MEMORY_AND_DISK*-requesting
-    // RDD's cached footprint). An RDD can produce both findings in one pass.
+    // Per-RDD cache-utilization proxies (this repo's own design: Spark event logs carry no
+    // block-access events, so a literal cache hit rate isn't derivable). Two per-RDD tiered
+    // checks over rddInfo snapshots: partial caching and disk spillover. An RDD can produce both.
     type: 'cacheUtilization', scope: 'app', order: 103, fixEffort: 'code', version: 1,
     docAnchor: '#memory-model',
     thresholds: {
@@ -1458,11 +1353,9 @@ export const DETECTORS             = [
     },
   },
   {
-    // Non-local task ratio across stage.localityStats (RACK_LOCAL + ANY vs.
-    // all tasks), the other half of dataflint's "Wasted Cores Ratio" alert;
-    // the idle-core half already lives in memoryUtilization's idleCores
-    // variant above. NO_PREF stays in the denominator only: it's what
-    // shuffle-read stages legitimately report with no locality problem.
+    // Non-local task ratio across stage.localityStats (RACK_LOCAL + ANY vs all tasks), the other
+    // half of the "Wasted Cores Ratio" (idle-core half is memoryUtilization's idleCores).
+    // NO_PREF stays in the denominator only: shuffle-read stages legitimately report it.
     type: 'coreLocality', scope: 'app', order: 103, fixEffort: 'config', version: 1,
     docAnchor: '#bottleneck-utilization',
     thresholds: { minTasks: 50, warnRatio: 0.15, critRatio: 0.35 },
@@ -1472,11 +1365,8 @@ export const DETECTORS             = [
     )                 {
       const { totalTasks, nonLocalTasks, ratio } = computeCoreLocalityRatio([...ctx.stages.values()]);
       if (totalTasks == null || totalTasks < this.thresholds.minTasks) return null;
-      // computeCoreLocalityRatio (src/core-locality-ratio.ts) only ever returns
-      // `ratio: null` together with `totalTasks: null` (its EMPTY sentinel sets
-      // both at once); the `totalTasks == null` guard above already rules that
-      // out, so `ratio` is guaranteed non-null here even though the function's
-      // declared return type keeps the two nullable independently.
+      // computeCoreLocalityRatio only returns ratio:null together with totalTasks:null (shared
+      // EMPTY sentinel); the totalTasks guard above rules that out, so ratio is non-null here.
       if (ratio  < this.thresholds.warnRatio) return null;
 
       const value = Math.round(ratio  * 100);
@@ -1484,8 +1374,7 @@ export const DETECTORS             = [
         type: 'coreLocality', stageId: null,
         impactBand: ratio  >= this.thresholds.critRatio ? 'critical' : 'warning',
         metric: 'nonLocalRatio', value,
-        // Raw count behind the ratio, for the impact estimator's network-fetch-penalty
-        // figure. Non-null whenever totalTasks is (both come from the same EMPTY sentinel).
+        // Raw count behind the ratio, for the impact estimator. Non-null whenever totalTasks is.
         nonLocalTaskCount: nonLocalTasks ,
         confidence: 'low',
         validationRequired: 'The 15%/35% non-local-ratio thresholds (and the 50-task minimum) are unvalidated design-spike values: no external tool publishes an equivalent metric to calibrate against. Confirm against known-good/known-bad real logs before trusting the impact-band split.',
@@ -1494,11 +1383,9 @@ export const DETECTORS             = [
     },
   },
   {
-    // Short-lived executors: an executor stood up and torn down before it
-    // could do useful work: wasteful re-provisioning, not normal scale-down.
-    // Reuses the same executorsAdded/executorsRemoved matching logic as
-    // `utilization` above (no new data extraction), but measures lifetime
-    // against a threshold instead of aggregate active-time.
+    // Short-lived executors: stood up and torn down before doing useful work (wasteful
+    // re-provisioning, not normal scale-down). Reuses utilization's add/remove matching, but
+    // measures lifetime against a threshold instead of aggregate active-time.
     type: 'autoscalingChurn', scope: 'app', order: 103, fixEffort: 'config', version: 1,
     confidence: 'low',
     thresholds: { shortLivedMs: 120_000, warningPct: 0.30, criticalPct: 0.60, minExecutors: 5 },
@@ -1510,7 +1397,7 @@ export const DETECTORS             = [
       ctx             ,
     )                 {
       const { app, executorsAdded, executorsRemoved } = ctx;
-      if (executorsAdded.length === 0 || app.endTime == null) return null;
+      if (!app || executorsAdded.length === 0 || app.endTime == null) return null;
       if (executorsAdded.length < this.thresholds.minExecutors) return null;
 
       const removedAt = new Map                ();
@@ -1540,10 +1427,8 @@ export const DETECTORS             = [
     },
   },
   {
-    // Cross-execution relation reuse (repurposed from the old RDD-lineage
-    // heuristic, which surfaced only internal query-engine RDDs on DataFrame/
-    // SQL workloads; see docs/adr/0009-caching-opportunity-relation-reuse.md).
-    // Flags an input relation scanned by two or more SQL executions in one run.
+    // Cross-execution relation reuse: flags an input relation scanned by two or more SQL
+    // executions in one run, firing on real relation names (parquet:..., jdbc:...).
     type: 'cachingOpportunity', scope: 'app', order: 105, fixEffort: 'code', version: 1,
     docAnchor: '#bottleneck-utilization',
     thresholds: { minExecutions: 2 },
@@ -1566,12 +1451,10 @@ export const DETECTORS             = [
        
                                                                                             
 
-      // relationId -> { format, relation, executionIds:Set, executionBytes: Map<execId, bytes> }
       const byRelation = new Map                     ();
       for (const exec of sql.values()) {
         if (!exec.planTree) continue;
-        // Dedupe relations within one execution (self-joins count once), summing
-        // this execution's read bytes per relation across its scan nodes.
+        // Dedupe relations within one execution (self-joins count once), summing read bytes per relation.
         const perExec = new Map                ();
         walkPlanTree(exec.planTree, (node) => {
           const rid = scanRelationId(node.name ?? '', node.detail ?? '');
@@ -1591,15 +1474,13 @@ export const DETECTORS             = [
         }
       }
 
-      // fingerprint -> { operator, exampleNode, executionIds:Set, executionBytes:Map<execId,bytes>, ancestorFingerprints:Set<fingerprint>, leafRelationRids:Set<rid> }
       const byComposite = new Map                        ();
       for (const exec of sql.values()) {
         if (!exec.planTree) continue;
         const candidates = findCompositeCandidates(exec.planTree);
         const fingerprintByNode = new Map                  (candidates.map((c)                     => [c.node, c.fingerprint]));
 
-        // Dedupe identical fingerprints within this execution (repeated
-        // identical composite counts once, mirroring the leaf perExec dedupe).
+        // Dedupe identical fingerprints within this execution (repeated composite counts once).
         const perExecComposite = new Map                             ();
         for (const c of candidates) {
           let agg = perExecComposite.get(c.fingerprint);
@@ -1636,12 +1517,10 @@ export const DETECTORS             = [
         }
       }
 
-      // Qualifying = has enough distinct executions on its own. Nested-dedupe:
-      // if a qualifying composite has a qualifying ANCESTOR composite, it is
-      // subsumed: fully (equal execution sets) or partially (residual).
+      // Qualifying = enough distinct executions on its own. Nested-dedupe: a qualifying composite
+      // with a qualifying ANCESTOR is subsumed, fully (equal sets) or partially (residual).
       const isQualifying = (fp        )          =>
         byComposite.has(fp) && byComposite.get(fp) .executionIds.size >= this.thresholds.minExecutions;
-      // fingerprint -> { finalExecutionIds:Set, suppressed:boolean }
       const compositeResolutions = new Map                             ();
       for (const [fingerprint, agg] of byComposite) {
         if (!isQualifying(fingerprint)) { compositeResolutions.set(fingerprint, { finalExecutionIds: agg.executionIds, suppressed: true }); continue; }
@@ -1658,7 +1537,7 @@ export const DETECTORS             = [
       const compositeVerb                                             = { join: ['joined', 'join'], union: ['unioned', 'union'] };
 
       const out            = [];
-      // rid -> Set<execId> covered by an emitted composite (for leaf suppression, Task 6)
+      // rid -> Set<execId> covered by an emitted composite, for leaf suppression.
       const coveredExecutionsByRid = new Map                     ();
       for (const [fingerprint, agg] of byComposite) {
         const resolution = compositeResolutions.get(fingerprint) ;
@@ -1744,10 +1623,8 @@ export const DETECTORS             = [
       let totalTasks = 0, failedTasks = 0;
       for (const s of stages.values()) { totalTasks += s.taskCount ?? 0; failedTasks += s.failedTasks ?? 0; }
       const taskFailureRate = totalTasks > 0 ? failedTasks / totalTasks : 0;
-      // Average wall-clock duration of the failed jobs, for the impact estimator's
-      // cost-only "core-hours burned on work that was thrown away" figure. Jobs
-      // missing either timestamp are excluded rather than counted as zero-length;
-      // with no timed failed job at all the average is 0 (never NaN).
+      // Average wall-clock of failed jobs, for the impact estimator's cost-only figure. Jobs
+      // missing either timestamp are excluded (not counted as zero); with none timed the average is 0.
       const timedFailedJobs = failedJobList.filter(j => j.submissionTime != null && j.completionTime != null);
       const avgJobDurationMs = timedFailedJobs.length > 0
         ? timedFailedJobs.reduce((s, j) => s + (j.completionTime  - j.submissionTime ), 0) / timedFailedJobs.length
@@ -1858,12 +1735,13 @@ export const DETECTORS             = [
         const nodes             = [];
         for (const n of g.nodes) walkPlanTree(n, (node) => nodes.push(node));
         const stageIds = unionStageIds(nodes, fallbackStageIds);
+        // resolvePlanTree always sets id; safe downstream of it.
+        const planNodeIds = nodes.map((n) => n.id ).filter(Boolean);
         const touching = g.sampleRelation ? ` (touching ${g.sampleRelation})` : '';
         return {
-          type: 'duplicatePlanSubtree', executionId: sqlExec.id, stageIds,
-          // Fixed fallback: overwritten by deriveImpactBand whenever this finding
-          // gets a real wallClock estimate, which is the common case. Only
-          // surfaces on the rare miss (stage excluded from the occupancy sweep).
+          type: 'duplicatePlanSubtree', executionId: sqlExec.id, stageIds, planNodeIds,
+          // Fixed fallback: overwritten by deriveImpactBand when this finding gets a real
+          // wallClock estimate (the common case). Only surfaces on the rare occupancy-sweep miss.
           impactBand: 'warning', metric: 'subtreeOccurrences', value: g.occurrences,
           rootName: g.rootName, subtreeSize: g.subtreeSize, sampleRelation: g.sampleRelation,
           groupIndex: g.groupIndex, confidence: 'medium',
@@ -1908,8 +1786,9 @@ export const DETECTORS             = [
       const fallbackStageIds = stageIdsForSqlExec(sqlExec.id, ctx.stages);
       return hits.map(h => {
         const stageIds = unionStageIds([h.node], fallbackStageIds);
+        const planNodeIds = h.node.id ? [h.node.id] : [];
         return {
-          type: 'smallFiles', executionId: sqlExec.id, stageIds,
+          type: 'smallFiles', executionId: sqlExec.id, stageIds, planNodeIds,
           impactBand: 'warning',
           metric: 'avgFileSizeBytes', value: Math.round(h.avgBytes),
           fileCount: h.fileCount, direction: h.direction, nodeName: h.nodeName,
@@ -1921,10 +1800,9 @@ export const DETECTORS             = [
     },
   },
   {
-    // Entry-level type is an identifier only; it never appears on an
-    // emitted finding. Findings carry their own type ('underBroadcast' or
-    // 'overBroadcast') since one shared plan-walk covers both opposite-
-    // direction rules (dataflint JoinToBroadcastAlert / BroadcastTooLargeAlert).
+    // Entry-level type is an identifier only; it never appears on an emitted finding. Findings
+    // carry 'underBroadcast'/'overBroadcast' since one shared plan-walk covers both
+    // opposite-direction rules (JoinToBroadcastAlert / BroadcastTooLargeAlert).
     type: 'broadcastSizing', scope: 'sql', order: 132, fixEffort: 'config', version: 2,
     docAnchor: '#bottleneck-broadcast-sizing',
     thresholds: {
@@ -1959,6 +1837,8 @@ export const DETECTORS             = [
               const contributors = [...boundarySizeContributors(childA), ...boundarySizeContributors(childB)];
               out.push({
                 type: 'underBroadcast', executionId: sqlExec.id, stageIds: unionStageIds(contributors, fallbackStageIds),
+                // resolvePlanTree always sets id; safe downstream of it.
+                planNodeIds: contributors.map((n) => n.id ).filter(Boolean),
                 impactBand: 'info', metric: 'smallerSideBytes', value: smaller,
                 largerSideBytes: larger,
                 recommendation: `The smaller input to this Sort Merge Join (${formatBytes(smaller)}) is well under the broadcast threshold relative to the larger side (${formatBytes(larger)}): this could have been a broadcast join. Consider a broadcast() hint or raising spark.sql.autoBroadcastJoinThreshold.`,
@@ -1966,17 +1846,18 @@ export const DETECTORS             = [
             }
           }
         }
-        if (node.name === 'BroadcastExchange') {
+        if (isBroadcastExchangeNode(node.name)) {
           const m = (node.metrics ?? []).find(x => x.name === 'data size');
           if (m && m.value > overBroadcastBytes) {
-            // The BroadcastExchange node's own metrics are computed on the
-            // driver and never appear on any TaskEnd (node.stageIds is
-            // always empty in real data); its child carries the
-            // executor-side metrics, so only the child is unioned in.
+            // BroadcastExchange's own metrics are driver-computed and never on any TaskEnd
+            // (node.stageIds always empty in real data); its child carries the executor-side
+            // metrics, so only the child unions in.
             const child = (node.children ?? [])[0];
             out.push({
               type: 'overBroadcast', executionId: sqlExec.id,
               stageIds: unionStageIds(child ? [child] : [], fallbackStageIds),
+              // resolvePlanTree always sets id; safe downstream of it.
+              planNodeIds: [node.id ].filter(Boolean),
               impactBand: 'warning', metric: 'broadcastBytes', value: m.value,
               recommendation: `This broadcast (${formatBytes(m.value)}) exceeds the 1 GB threshold: check for a misapplied broadcast hint or a misconfigured spark.sql.autoBroadcastJoinThreshold.`,
             });