sparkforensics-mcp 0.3.0 → 0.5.0

package/bin/sparkforensics-mcp.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { existsSync } from 'node:fs';
+import { parseArgs } from 'node:util';
 import { join, dirname } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
@@ -7,16 +8,20 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 const binDir = dirname(fileURLToPath(import.meta.url));
 const pkgDir = dirname(binDir);
 
-// vendor-core/ exists only in a published install (populated by vendor-core.mjs
-// at pack time); the monorepo falls back to the packages/core/src/ sibling.
+// vendor-core/ is populated by vendor-core.mjs at pack time. In the monorepo the
+// packages/core/src/ sibling's load-vendored.js is used, which prefers a leftover
+// vendor-core/ only while it still matches core/src and warns when it does not.
 // load-vendored.js is the one module located by hand; the rest load through its
 // exported loadVendored().
-async function loadCreateMcpServer() {
-  const vendoredHelper = join(pkgDir, 'vendor-core', 'load-vendored.js');
-  const helperPath = existsSync(vendoredHelper) ? vendoredHelper : join(pkgDir, '..', 'core', 'src', 'load-vendored.js');
+async function loadCoreModule(moduleName) {
+  const srcHelper = join(pkgDir, '..', 'core', 'src', 'load-vendored.js');
+  const helperPath = existsSync(srcHelper) ? srcHelper : join(pkgDir, 'vendor-core', 'load-vendored.js');
   const { loadVendored } = await import(pathToFileURL(helperPath).href);
-  const mod = await loadVendored(pkgDir, 'mcp-server-factory');
-  return mod.createMcpServer;
+  return loadVendored(pkgDir, moduleName);
+}
+
+async function loadCreateMcpServer() {
+  return (await loadCoreModule('mcp-server-factory')).createMcpServer;
 }
 
 // Tool names come from the server the bin actually builds, so --help can't drift
@@ -24,25 +29,51 @@ async function loadCreateMcpServer() {
 // no I/O. _registeredTools is the SDK's registry; the MCP package test checks that
 // this list matches what listTools reports.
 function usage(toolNames) {
-  return `Usage: sparkforensics-mcp
+  return `Usage: sparkforensics-mcp [--thresholds <file>]
 
 Starts the SparkForensics MCP server, speaking the MCP protocol over
 stdio. Point an MCP client (Claude Desktop, Claude Code, etc.) at this
 command; it exposes ${toolNames.length} tools for diagnosing Apache Spark event logs:
 ${toolNames.join(', ')}.
 
+  --thresholds <file>  Run every tool's detectors with the threshold overrides in
+                       this JSON file ({"<detector>": {"<threshold>": value}}).
+                       Findings a tuned detector produces carry tunedThresholds.
+                       An unreadable or invalid file stops the server from starting.
+
 See https://github.com/shuffle-works/sparkforensics#readme for details.
 `;
 }
 
 async function main() {
-  if (process.argv.includes('--help') || process.argv.includes('-h')) {
+  // Not strict: arguments this server never read before stay ignored, as they always were.
+  const { values } = parseArgs({
+    args: process.argv.slice(2), strict: false,
+    options: { thresholds: { type: 'string' }, help: { type: 'boolean', short: 'h' } },
+  });
+  if (values.help) {
     const createMcpServer = await loadCreateMcpServer();
     process.stderr.write(usage(Object.keys(createMcpServer()._registeredTools)));
     return;
   }
+  let thresholds;
+  if (values.thresholds !== undefined) {
+    if (typeof values.thresholds !== 'string') {
+      process.stderr.write('--thresholds requires a file path.\n');
+      process.exitCode = 2;
+      return;
+    }
+    // Refuse to start rather than serve default-threshold results the user meant to change.
+    try {
+      thresholds = (await loadCoreModule('cli/threshold-config')).loadThresholdOverrides(values.thresholds);
+    } catch (e) {
+      process.stderr.write(`--thresholds: ${e.message}\n`);
+      process.exitCode = 2;
+      return;
+    }
+  }
   const createMcpServer = await loadCreateMcpServer();
-  const server = createMcpServer();
+  const server = createMcpServer({ thresholds });
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparkforensics-mcp",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "mcpName": "io.github.shuffle-works/sparkforensics-mcp",
   "type": "module",
   "license": "MIT",

package/vendor-core/allocation.js

@@ -0,0 +1,106 @@
+import { parseSparkMemoryMB } from './spark-memory.js';
+                                                                                         
+
+const MS_PER_HOUR = 3_600_000;
+const MIB_PER_GIB = 1024;
+// Spark's documented floor and factor for the default executor memory overhead
+// (spark.executor.memoryOverhead = max(factor * executor memory, 384 MiB)).
+const MIN_OVERHEAD_MIB = 384;
+const DEFAULT_OVERHEAD_FACTOR = 0.1;
+
+                             
+                                                                                                   
+                           
+                                                                                             
+                                                        
+                               
+ 
+
+                                  
+                           
+                             
+                                                                  
+ 
+
+/** The latest timestamp the log records: the application start and end and every stage and
+ * executor event. Where a log with no ApplicationEnd stops. */
+export function lastObservedTimestamp(input                 )                {
+  let last                = null;
+  const take = (t                           )       => {
+    if (typeof t === 'number' && Number.isFinite(t) && t > 0 && (last == null || t > last)) last = t;
+  };
+  take(input.app?.startTime);
+  take(input.app?.endTime);
+  for (const s of input.stages.values()) { take(s.submittedAt); take(s.completedAt); }
+  for (const e of [...input.executors.added, ...input.executors.removed]) take(e.timestamp);
+  return last;
+}
+
+// Spark's default executor memory when spark.executor.memory is unset.
+const DEFAULT_EXECUTOR_MEMORY_MIB = 1024;
+
+// One container's memory in MiB, as Spark requests it from the cluster manager: executor heap,
+// plus overhead, plus off-heap and PySpark worker memory when configured. Null when the log
+// records no Spark properties (nothing to tell a default from a missing config) or a memory key it
+// does record cannot be read.
+function executorMemoryMiB(app                     )                {
+  const config = app?.config;
+  if (config == null) return null;
+  // undefined: key absent; null: present but unreadable.
+  const mib = (key        )                            => (config[key] == null ? undefined : parseSparkMemoryMB(config[key]));
+  const heap = mib('spark.executor.memory') ?? (config['spark.executor.memory'] == null ? DEFAULT_EXECUTOR_MEMORY_MIB : null);
+  if (heap == null) return null;
+
+  let overhead = mib('spark.executor.memoryOverhead');
+  if (overhead === undefined) overhead = mib('spark.yarn.executor.memoryOverhead'); // legacy key
+  if (overhead === undefined) {
+    const factor = Number.parseFloat(config['spark.executor.memoryOverheadFactor'] ?? '');
+    overhead = Math.max(MIN_OVERHEAD_MIB, Math.round(heap * (Number.isFinite(factor) && factor > 0 ? factor : DEFAULT_OVERHEAD_FACTOR)));
+  }
+  const offHeap = String(config['spark.memory.offHeap.enabled']).toLowerCase() === 'true' ? mib('spark.memory.offHeap.size') ?? 0 : 0;
+  const pyspark = mib('spark.executor.pyspark.memory') ?? 0;
+  if (overhead === null || offHeap === null || pyspark === null) return null;
+  return heap + overhead + offHeap + pyspark;
+}
+
+/** Allocated core-hours and memory GiB-hours from the executor lifecycle: each executor counts
+ * from its ExecutorAdded timestamp to its first later ExecutorRemoved timestamp. One with no
+ * removal closes at the application end when the log has one, else at the last timestamp the log
+ * records (a cut-off log). Cores are the ExecutorAdded event's Total Cores, else
+ * spark.executor.cores; memory per executor is spark.executor.memory (default 1g) plus the
+ * overhead (spark.executor.memoryOverhead, else the legacy spark.yarn.executor.memoryOverhead,
+ * else the larger of 384 MiB and spark.executor.memoryOverheadFactor, default 0.1, times the
+ * memory), plus spark.memory.offHeap.size when spark.memory.offHeap.enabled is true, plus
+ * spark.executor.pyspark.memory.
+ * Null, never 0, for a figure whose inputs the log lacks. */
+export function computeAllocation(input                 )             {
+  const added = input.executors.added.filter((e)                          => e.kind === 'added');
+  if (added.length === 0) return { coreHours: null, memoryGbHours: null };
+  const removedAt = new Map                  ();
+  for (const e of input.executors.removed) {
+    if (e.kind !== 'removed') continue;
+    const times = removedAt.get(e.executorId);
+    if (times) times.push(e.timestamp); else removedAt.set(e.executorId, [e.timestamp]);
+  }
+  const closeAt = input.app?.endTime ?? lastObservedTimestamp(input);
+  const configuredCores = Number.parseInt(input.app?.config?.['spark.executor.cores'] ?? '', 10);
+  const memoryMiB = executorMemoryMiB(input.app);
+
+  let coreMs = 0;
+  let memoryMiBMs = 0;
+  let coresKnown = true;
+  const seen = new Set        ();
+  for (const e of added) {
+    if (seen.has(e.executorId)) continue; // a replayed ExecutorAdded is the same executor
+    seen.add(e.executorId);
+    const removal = (removedAt.get(e.executorId) ?? []).filter((t) => t >= e.timestamp).sort((a, b) => a - b)[0];
+    const aliveMs = Math.max(0, (removal ?? closeAt ?? e.timestamp) - e.timestamp);
+    const cores = e.totalCores > 0 ? e.totalCores : Number.isFinite(configuredCores) ? configuredCores : null;
+    if (cores == null) coresKnown = false; else coreMs += cores * aliveMs;
+    memoryMiBMs += (memoryMiB ?? 0) * aliveMs;
+  }
+  return {
+    coreHours: coresKnown ? coreMs / MS_PER_HOUR : null,
+    memoryGbHours: memoryMiB != null ? memoryMiBMs / MIB_PER_GIB / MS_PER_HOUR : null,
+  };
+}

package/vendor-core/analyzer.js

@@ -1,14 +1,28 @@
-import { DETECTORS,               } from './detectors.js';
+import { DETECTORS, ENTRY_BY_TYPE,                                                                                     } from './detectors.js';
+import { effectiveThresholds, findingTunedThresholds, overridesFor, tunedThresholdsNote } from './threshold-overrides.js';
 import { computePeakConcurrentCores } from './core-count.js';
 import { assertNever } from './assert-never.js';
-import { estimateImpact } from './impact-estimator.js';
+import { estimateImpact,                  } from './impact-estimator.js';
 import { computeOccupancy,                     } from './occupancy.js';
-import { deriveImpactBand } from './impact-band.js';
+import { deriveImpactBand, IMPACT_FLOOR_PCT_CRIT, IMPACT_FLOOR_PCT_WARN,                       } from './impact-band.js';
 import { IMPACT_BAND_ORDER } from './format-utils.js';
              
-                                                                                
+                                                                                                                         
                     
 
+// The runner reads each entry through the Detector contract, not its own precise `as const` shape:
+// the scope switch below calls each entry's bound detect with that scope's target.
+const detectors                      = DETECTORS;
+
+                                 
+                                                                                              
+                                                                                                  
+                                                                                                
+                                                                                              
+                                                                    
+                                  
+ 
+
 // FNV-1a 32-bit stable string hash: deterministic finding id across runs, no timestamps/randomness.
 function fnv1a(str        )         {
   let h = 0x811c9dc5;
@@ -19,66 +33,97 @@ function fnv1a(str        )         {
   return (h >>> 0).toString(16).padStart(8, '0');
 }
 
+// The id hash's discriminator slots, in the order it has always joined them: reordering or renaming
+// one changes every finding id, which needs an EVIDENCE_SCHEMA_VERSION bump.
+const DISCRIMINATOR_SLOTS = [
+  'host', 'executorId', 'rule', 'variant', 'dimension',
+  'direction', 'nodeName', 'rootName', 'subtreeSize', 'groupIndex', 'largerSideBytes',
+  'rddId', 'relation', 'format', 'operator', 'executionIds',
+]         ;
+                                                              
+
+// Per type, the fields that tell apart sibling findings sharing one location and metric; without
+// them those siblings hash to one id:
+//   slowHost (host), memoryUtilization (executorId), partitionSizing (rule);
+//   cacheUtilization (rddId+variant), cachingOpportunity (relation/format for leaf,
+//     operator+relation for composite, executionIds as last resort);
+//   smallFiles (direction/nodeName), duplicatePlanSubtree (groupIndex is the real
+//     uniqueness guarantee: rootName+subtreeSize can collide across groups),
+//     underBroadcast (value+largerSideBytes per node/side).
+// memoryUtilization leaves out `rule`: one heap band per executor, so executorId is already
+// unique and folding rule in risks id churn if band logic changes. partitionSizing keeps
+// `rule`: a stage can emit several rules at once sharing stageId+metric.
+const ID_DISCRIMINATORS                                                                              = {
+  skew: [], stageShape: ['rule'], shuffle: [], partitionSizing: ['rule'], spill: [], gc: ['direction'],
+  slowHost: ['host', 'executorId', 'variant', 'dimension'], stageSlowness: [], stageFailed: ['variant'],
+  failures: [], straggler: [], speculationWaste: [], retryWaste: [], tinyTask: [],
+  incompleteRun: [], coldStart: [], utilization: [], memoryUtilization: ['executorId', 'variant'],
+  cacheUtilization: ['variant', 'rddId'], coreLocality: [], autoscalingChurn: [],
+  cachingOpportunity: ['variant', 'relation', 'format', 'operator', 'executionIds'],
+  jobFailureRate: [], configAudit: [],
+  duplicatePlanSubtree: ['rootName', 'subtreeSize', 'groupIndex'], smallFiles: ['direction', 'nodeName'],
+  underBroadcast: ['largerSideBytes'], overBroadcast: [],
+};
+
+// ID_DISCRIMINATORS as Sets, built once: findingId runs once per finding.
+const ID_DISCRIMINATOR_SETS = new Map                                        (
+  Object.entries(ID_DISCRIMINATORS).map(([type, slots]) => [type, new Set                   (slots)]),
+);
+
+// Location key: stage, else SQL execution, else audited config property.
+function locationKey(f         )                  {
+  if (f.stageId != null) return f.stageId;
+  if ('executionId' in f) return f.executionId;
+  if (f.type === 'configAudit') return f.property;
+  return '';
+}
+
 export function findingId(f         )         {
-  // Location key: stage, else SQL execution, else audited config property.
-  const locKey = f.stageId ?? f.executionId ?? f.property ?? '';
-  // Discriminators for detectors that emit multiple findings on the same
-  // location+metric; without them these siblings hash to one id:
-  //   slowHost (host), memoryUtilization (executorId+dimension), partitionSizing (rule);
-  //   cacheUtilization (rddId+variant), cachingOpportunity (relation/format for leaf,
-  //     operator+relation for composite, executionIds as last resort);
-  //   smallFiles (direction/nodeName), duplicatePlanSubtree (groupIndex is the real
-  //     uniqueness guarantee: rootName+subtreeSize can collide across groups),
-  //     broadcastSizing (value+largerSideBytes per node/side).
-  // memoryUtilization excludes `rule`: one heap band per executor, so executorId is already
-  // unique and folding rule in risks id churn if band logic changes. partitionSizing keeps
-  // `rule`: a stage can emit several rules at once sharing stageId+metric.
-  const rule = f.type === 'memoryUtilization' ? undefined : f.rule;
-  const disc = [
-    f.host, f.executorId, rule, f.variant, f.dimension,
-    f.direction, f.nodeName, f.rootName, f.subtreeSize, f.groupIndex, f.largerSideBytes,
-    f.rddId, f.relation, f.format, f.operator,
-    f.executionIds ? f.executionIds.join(',') : '',
-  ].map((v) => v ?? '').join('|');
-  return fnv1a(`${f.type}|${locKey}|${f.metric ?? ''}|${f.value ?? ''}|${disc}`);
+  const fields = f                                                          ;
+  const listed = ID_DISCRIMINATOR_SETS.get(f.type);
+  const disc = DISCRIMINATOR_SLOTS.map((slot) => {
+    const v = listed?.has(slot) ? fields[slot] : undefined;
+    return Array.isArray(v) ? v.join(',') : v ?? '';
+  }).join('|');
+  return fnv1a(`${f.type}|${locationKey(f)}|${f.metric ?? ''}|${f.value ?? f.valueText ?? ''}|${disc}`);
 }
 
-// skew's max/median branch (stage.taskCount below minTasksForP95) and straggler are both driven
-// by the identical (taskDurationMax - taskDurationP50) delta on the same stage: the same
-// dominant outlier task reported by two detectors, each independently clipped (see "Overlap
-// caveat: skew / straggler" in impact-estimation.md). skew's P95/median branch samples a
-// different task and stays independent. Flags both sides via validationRequired (rather than
-// suppressing either) so neither finding's own diagnostic value is lost; the flag rides the same
+// skew (either branch) and straggler both claim the stage's replayed tail recovery
+// (tailReplayRecoveryMs via tailRecoveryMs): the same slow-task tail reported by two detectors
+// (see "Overlap caveat: skew / straggler" in impact-estimation.md). skew's branch only changes
+// the fallback single-task delta on a stage without the replay, so every skew + straggler pair
+// on a stage is flagged. Flags both sides via validationRequired (rather than suppressing
+// either) so neither finding's own diagnostic value is lost; the flag rides the same
 // confidence-caveat UI a reader already sees before trusting either finding's magnitude.
 function overlapNote(otherType                      )         {
-  return `This overlaps with the ${otherType} finding on this stage: both are driven by the same dominant outlier task, so don't add their recoverable-time figures together.`;
+  return `This overlaps with the ${otherType} finding on this stage: both measure the same slow-task tail, so don't add their recoverable-time figures together.`;
 }
 
 function flagSkewStragglerOverlap(findings           )       {
-  const maxMedianSkewStages = new Set(
-    findings.filter((f) => f.type === 'skew' && f.metric === 'max/median' && f.stageId != null).map((f) => f.stageId),
+  const skewStages = new Set(
+    findings.filter((f) => f.type === 'skew' && f.stageId != null).map((f) => f.stageId),
   );
-  if (maxMedianSkewStages.size === 0) return;
+  if (skewStages.size === 0) return;
   const stragglerStages = new Set(
     findings.filter((f) => f.type === 'straggler' && f.stageId != null).map((f) => f.stageId),
   );
-  const overlapStages = new Set([...maxMedianSkewStages].filter((id) => stragglerStages.has(id)));
+  const overlapStages = new Set([...skewStages].filter((id) => stragglerStages.has(id)));
   if (overlapStages.size === 0) return;
   for (const f of findings) {
     if (f.stageId == null || !overlapStages.has(f.stageId)) continue;
     const note = f.type === 'skew' ? overlapNote('straggler') : f.type === 'straggler' ? overlapNote('skew') : null;
     if (!note) continue;
-    f.validationRequired = f.validationRequired ? `${f.validationRequired} ${note}` : note;
+    f.validationRequired = [f.validationRequired, note].filter(Boolean).join(' ');
   }
 }
 
-function push(out           , entry          , result                            )       {
+function push(out           , entry          , result                            , tuned                         = null)       {
   if (!result) return;
   const detectorVersion = entry.version ?? 1;
   for (const f of (Array.isArray(result) ? result : [result])) {
     if (!f) continue;
-    if (entry.suppressWhen && entry.suppressWhen(f, out)) continue;
     const stamped = { ...f, docAnchor: f.docAnchor ?? entry.docAnchor, detectorVersion };
+    if (tuned) stamped.tunedThresholds = tuned;
     const id = findingId(stamped);
     // Dedup guard: same id => same finding, keep first. Correctness depends on
     // findingId's discriminators being unique per distinct finding, not on this line.
@@ -87,6 +132,50 @@ function push(out           , entry          , result
   }
 }
 
+// A tuned finding's caveat, once its estimate is known: only a finding with an estimate figure
+// (wall-clock or raw waste) says that figure is unvalidated.
+function noteTunedThresholds(findings           )       {
+  for (const f of findings) {
+    if (!f.tunedThresholds) continue;
+    const hasFigure = f.impactEstimate != null && f.impactEstimate.basis !== 'informational';
+    const note = tunedThresholdsNote(f.tunedThresholds, hasFigure);
+    f.validationRequired = f.validationRequired ? `${f.validationRequired} ${note}` : note;
+  }
+}
+
+// skew and straggler gate on floorPctWarn/floorPctCrit thresholds that default to the band's own
+// floors, so a finding they admit at their warn floor grades at least warning. A tuned floor grades
+// that entry's findings too; a type whose entry has no such threshold keeps the defaults.
+function bandFloors(type        , overrides                    )                          {
+  const entry = ENTRY_BY_TYPE.get(type);
+  if (!entry) return null;
+  const { floorPctWarn, floorPctCrit } = effectiveThresholds(entry, overrides);
+  return {
+    warnPct: typeof floorPctWarn === 'number' ? floorPctWarn : IMPACT_FLOOR_PCT_WARN,
+    critPct: typeof floorPctCrit === 'number' ? floorPctCrit : IMPACT_FLOOR_PCT_CRIT,
+  };
+}
+
+// An entry's `suppressedBy` names another entry: drop its findings on every stage that entry
+// flagged. Runs once every detector has, so neither declaration order matters, and reads the
+// unsuppressed findings, so the result doesn't depend on which suppression is applied first.
+function applySuppression(out           )            {
+  const dropped = new Map                     ();
+  for (const entry of detectors) {
+    if (!entry.suppressedBy) continue;
+    const suppressorTypes = new Set        (
+      detectors.filter((d) => d.type === entry.suppressedBy).flatMap((d) => d.emits),
+    );
+    for (const type of entry.emits) {
+      const stagesToDrop = dropped.get(type) ?? new Set        ();
+      for (const f of out) if (suppressorTypes.has(f.type) && f.stageId != null) stagesToDrop.add(f.stageId);
+      dropped.set(type, stagesToDrop);
+    }
+  }
+  if (dropped.size === 0) return out;
+  return out.filter((f) => f.stageId == null || !dropped.get(f.type)?.has(f.stageId));
+}
+
 // `app` widened to `SparkAppInfo | null` to match real callers (AppModel.app is
 // nullable at the type level); every detector below tolerates a null app.
 export function analyze(
@@ -97,6 +186,7 @@ export function analyze(
   jobs                  ,
   sql                            = new Map(),
   runAggregates                       = null,
+  { thresholds }                 = {},
 )            {
   // `app ?? {}`: detectors tolerate a null app (malformed logs), so this must too.
   // computePeakConcurrentCores (not computeTotalCores): the occupancy ceiling needs a
@@ -108,37 +198,55 @@ export function analyze(
     executorsAdded                                                                         ,
     executorsRemoved                                                    ,
   );
-  // Computed once so detectors gate impact band on the same occupancy-clipped waste
-  // estimateImpact displays as savings, not a raw pre-clip delta the two passes would disagree on.
-  const occupancy = computeOccupancy(stages                                          , totalCores);
-  const ctx = {
-    app, stages, executorsAdded, executorsRemoved, jobs, sql, runAggregates, occupancy,
+  // One occupancy sweep per analysis, shared by the detectors' runtime floors and every entry's
+  // estimate(), so a floor gates on the same occupancy-clipped figure displayed as savings.
+  const impact              = {
+    stages, totalCores, sql,
+    occupancy: computeOccupancy(stages                                          , totalCores),
+  };
+  // The one cast from the posted-model types to the detector-side shapes: types.ts's Stage and
+  // SqlExecution carry a catch-all index signature, while every field DetectorStage/DetectorSqlExec
+  // declare is one finalizeStage and event-handlers.ts always set (see detectors.ts's header).
+  const ctx              = {
+    app, jobs, executorsAdded, executorsRemoved, runAggregates, impact,
+    stages: stages                                    ,
+    sql: sql                                 ,
   };
   const out            = [];
-  for (const d of DETECTORS) {
+  for (const d of detectors) {
     if (d.inScorecard === false) continue;
+    const overrides = overridesFor(d, thresholds);
+    const tuned = findingTunedThresholds(d, thresholds);
     switch (d.scope) {
-      case 'stage':
-        for (const s of stages.values()) push(out, d, d.detect(s, ctx));
+      case 'stage': {
+        const detect = d.withThresholds(overrides);
+        for (const s of ctx.stages.values()) push(out, d, detect(s, ctx), tuned);
         break;
-      case 'sql':
-        for (const e of sql.values()) push(out, d, d.detect(e, ctx));
+      }
+      case 'sql': {
+        const detect = d.withThresholds(overrides);
+        for (const e of ctx.sql.values()) push(out, d, detect(e, ctx), tuned);
         break;
+      }
       case 'app':
+        push(out, d, d.withThresholds(overrides)(ctx), tuned);
+        break;
       case 'config':
-        push(out, d, d.detect(ctx));
+        push(out, d, d.withThresholds(overrides)(ctx                               ), tuned);
         break;
       default:
-        assertNever(d.scope);
+        assertNever(d);
     }
   }
-  estimateImpact(out, stages, totalCores);
-  deriveImpactBand(out, app);
-  flagSkewStragglerOverlap(out);
+  const findings = applySuppression(out);
+  estimateImpact(findings, impact);
+  noteTunedThresholds(findings);
+  deriveImpactBand(findings, app, thresholds ? (type) => bandFloors(type, thresholds) : undefined);
+  flagSkewStragglerOverlap(findings);
   // Ascending IMPACT_BAND_ORDER (critical 0 -> info 2) puts the worst band first;
   // stable sort keeps DETECTORS declaration order within a band.
-  out.sort((a, b) => IMPACT_BAND_ORDER[a.impactBand] - IMPACT_BAND_ORDER[b.impactBand]);
-  return out;
+  findings.sort((a, b) => IMPACT_BAND_ORDER[a.impactBand] - IMPACT_BAND_ORDER[b.impactBand]);
+  return findings;
 }
 
 // Memoizes auditConfig by `app` identity (like evidence-report.ts's jsonCache) so config detectors
@@ -149,10 +257,10 @@ const auditConfigCache = new WeakMap                         ();
 
 function computeAuditConfig(app                     )            {
   const out            = [];
-  for (const d of DETECTORS) if (d.scope === 'config') push(out, d, d.detect({ app }));
-  // configAudit's impact case is unconditionally costOnly('none'): needs no stages/totalCores,
-  // an empty stages map gives parity with analyze().
-  estimateImpact(out, new Map());
+  for (const d of detectors) if (d.scope === 'config') push(out, d, d.withThresholds()({ app }));
+  // configAudit's estimate is unconditionally costOnly('none'): needs no stages/totalCores, so an
+  // empty context gives parity with analyze().
+  estimateImpact(out, { stages: new Map(), occupancy: new Map(), totalCores: 0 });
   deriveImpactBand(out, app);
   return out.map((f) => ({ ...f, stageId: f.stageId ?? null }));
 }

package/vendor-core/check-coverage.js

@@ -0,0 +1,88 @@
+// Which checks a log could actually run. Shared by the dashboard (verdict, top bar, Clean checks)
+// and the CLI/MCP evidence report, so a check the log lacked the data for never reads as passed on
+// one path and "not checked" on another.
+import { detectorCatalog } from './detectors.js';
+import { isRealFinding } from './recommendation-rollup.js';
+import { summarizeRunOutcome } from './run-outcome.js';
+                                                    
+
+export const NO_FINISHED_STAGE_GAP = 'No stage in this log recorded an end, so the stage checks had nothing to measure.';
+export const INCOMPLETE_RUN_GAP =
+  'The log has no end-of-run record, so the core usage, memory and executor churn checks had no run length to measure.';
+
+/** True when at least one stage recorded both a start and an end, so the
+ * stage checks had something to measure. */
+export function hasFinishedStage(stages                    )          {
+  return [...stages.values()].some((stage) => stage.submittedAt != null && stage.completedAt != null);
+}
+
+/** A finding that reports a check could not run for lack of evidence (cache
+ * storage without block updates, memory without executor metrics), rather
+ * than a problem found. Its recommendation names the setting to turn on. */
+export function isEvidenceCaveat(finding         )          {
+  return ('dataUnavailable' in finding && finding.dataUnavailable === true) || !isRealFinding(finding);
+}
+
+/** App-level checks measured over the run's full span, which a log with no
+ * ApplicationEnd (an `incompleteRun` finding) cannot give them. */
+export const RUN_SPAN_CHECK_TYPES                      = new Set(['utilization', 'memoryUtilization', 'autoscalingChurn']);
+
+/** Detector types that measure each stage, read from the detector catalog. */
+export const PER_STAGE_CHECK_TYPES                      = new Set(
+  detectorCatalog().filter((entry) => entry.scope === 'stage').map((entry) => entry.type),
+);
+
+export function isIncompleteRun(allFindings           )          {
+  return allFindings.some((finding) => finding.type === 'incompleteRun');
+}
+
+/** What this log could not check, in plain sentences, each saying what to
+ * turn on for the next run where the detector names it. */
+export function verdictGaps(allFindings           , noFinishedStages         )           {
+  const gaps = new Set        ();
+  if (noFinishedStages) gaps.add(NO_FINISHED_STAGE_GAP);
+  if (isIncompleteRun(allFindings)) gaps.add(INCOMPLETE_RUN_GAP);
+  for (const finding of allFindings) {
+    if (isEvidenceCaveat(finding) && finding.recommendation) gaps.add(finding.recommendation);
+  }
+  return [...gaps];
+}
+
+/** The one rule for calling a run clean, shared by the verdict, the top bar
+ * and the evidence report: no finding at all, no failed job, and nothing the
+ * log lacked to run a check. */
+export function isCleanRun(appModel                                   , allFindings           )          {
+  if (summarizeRunOutcome(appModel.jobs, allFindings).failedJobs > 0) return false;
+  if (allFindings.some(isRealFinding)) return false;
+  return verdictGaps(allFindings, !hasFinishedStage(appModel.stages)).length === 0;
+}
+
+                                
+                                                                                                  
+                                  
+                                                                                        
+                                                                                        
+                                            
+ 
+
+/** The not-run rule for one run: an evidence caveat of that type, a per-stage
+ * check on a log where no stage finished, or a run-span check on a log with
+ * no ApplicationEnd. */
+export function checkCoverage(stages                    , allFindings           )                {
+  const noFinishedStages = !hasFinishedStage(stages);
+  const incomplete = isIncompleteRun(allFindings);
+  const caveatReasons = new Map                       ();
+  for (const finding of allFindings) {
+    if (!isEvidenceCaveat(finding)) continue;
+    if (!caveatReasons.get(finding.type)) caveatReasons.set(finding.type, finding.recommendation ?? null);
+  }
+  const notRunReason = (type        )                => {
+    const caveatReason = caveatReasons.get(type);
+    if (caveatReason) return caveatReason;
+    if (noFinishedStages && PER_STAGE_CHECK_TYPES.has(type)) return NO_FINISHED_STAGE_GAP;
+    if (incomplete && RUN_SPAN_CHECK_TYPES.has(type)) return INCOMPLETE_RUN_GAP;
+    // A caveat with no recommendation still means the check did not run.
+    return caveatReasons.has(type) ? 'The log lacked the data this check needs.' : null;
+  };
+  return { isNotRun: (type) => notRunReason(type) != null, notRunReason };
+}