sparkforensics-mcp 0.3.0 → 0.5.0

package/vendor-core/cli/budgets.js

@@ -1,8 +1,10 @@
 import { computeEfficiencyModel } from '../efficiency-model.js';
-import { computeSkewRatio, DETECTORS } from '../detectors.js';
+import { computeSkewRatio, ENTRY_BY_TYPE,                         } from '../detectors.js';
+import { effectiveThresholds } from '../threshold-overrides.js';
 import { IMPACT_BAND_ORDER } from '../format-utils.js';
                                                               
                                                                  
+                                                                
 
 const IMPACT_BANDS = Object.keys(IMPACT_BAND_ORDER)                ;
 
@@ -10,29 +12,33 @@ const IMPACT_BANDS = Object.keys(IMPACT_BAND_ORDER)                ;
                                                                     
                                                            
                                                                                   
+                                                                                                 
+                                         
  
                                
                                                                                             
-                                              
+                                                               
                                                 
                  
+                                                                            
+                  
  
 
-const skewDetector = DETECTORS.find((d) => d.type === 'skew');
-const SKEW_MIN_TASKS_FOR_P95 = skewDetector .thresholds .minTasksForP95          ;
+// The skew entry's minTasksForP95 under the run's overrides, so the budget measures the same
+// ratio (P95/median or max/median) the skew finding reports.
+function skewMinTasksForP95(thresholds                                )         {
+  return effectiveThresholds(ENTRY_BY_TYPE.get('skew') , thresholds).minTasksForP95          ;
+}
 
 function taskDataTrusted(appModel          )          {
   const entry = appModel.evidenceAvailability?.entries?.find((e) => e.key === 'taskCoreTime');
   return entry?.state === 'present';
 }
 
-// Finding.value is number|string (some detectors put text there); spill findings are
-// always numeric, so the typeof guard narrows without changing behavior for real input.
 function maxFindingValue(catalog           , type        )                {
   const values = catalog
     .filter((f) => f.type === type)
-    .map((f) => f.value ?? 0)
-    .filter((v)              => typeof v === 'number');
+    .map((f) => f.value ?? 0);
   return values.length > 0 ? Math.max(...values) : null;
 }
 
@@ -58,7 +64,7 @@ function checkSpill(appModel          , catalog           , maxSpillGb        )
     : { name: 'max-spill', status: 'pass', detail: `Peak stage spill ${maxBytes} bytes within budget ${budgetBytes} bytes.` };
 }
 
-function checkSkew(appModel          , maxSkewRatio        )               {
+function checkSkew(appModel          , maxSkewRatio        , minTasksForP95        )               {
   if (!taskDataTrusted(appModel)) {
     return { name: 'max-skew', status: 'inconclusive', detail: 'No trustworthy task-level evidence to measure skew.' };
   }
@@ -69,7 +75,7 @@ function checkSkew(appModel          , maxSkewRatio        )               {
   // Recompute the true ratio per stage: the skew detector floors findings at
   // thresholds.ratioWarn (3), so a stricter budget can't be enforced from catalog alone.
   const ratios = stages
-    .map((stage) => computeSkewRatio(stage, SKEW_MIN_TASKS_FOR_P95))
+    .map((stage) => computeSkewRatio(stage, minTasksForP95))
     .filter((r) => r !== null)
     .map((r) => r.ratio);
   if (ratios.length === 0) {
@@ -97,43 +103,47 @@ function checkFailedTaskRate(appModel          , catalog           , maxPct
   return { name: 'max-failed-task-rate', status: 'pass', detail: `No job-failure-rate finding: task failure rate is below the detector's reporting floor.` };
 }
 
+// Busy core time: the share of available executor core time that ran tasks, 100 minus the
+// dashboard's "Unused core time". Not the dashboard's Efficiency tile (the share of wall-clock with
+// a stage running), so the detail never calls it "Efficiency".
 function checkEfficiency(appModel          , minPct        )               {
   if (!taskDataTrusted(appModel)) {
-    return { name: 'min-efficiency', status: 'inconclusive', detail: 'No trustworthy task-level evidence to measure efficiency.' };
+    return { name: 'min-efficiency', status: 'inconclusive', detail: 'No trustworthy task-level evidence to measure busy core time.' };
   }
   const model = computeEfficiencyModel({
     app: appModel.app, stages: appModel.stages,
-    executorsAdded: appModel.executors.added, runAggregates: appModel.runAggregates,
+    executorsAdded: appModel.executors.added, executorsRemoved: appModel.executors.removed,
+    runAggregates: appModel.runAggregates,
   });
   if (model.wastagePct == null) {
-    return { name: 'min-efficiency', status: 'inconclusive', detail: 'Efficiency could not be computed (no available compute hours).' };
+    return { name: 'min-efficiency', status: 'inconclusive', detail: 'Busy core time could not be computed (no available compute hours).' };
   }
-  const efficiencyPct = 100 - model.wastagePct;
-  return efficiencyPct < minPct
-    ? { name: 'min-efficiency', status: 'violation', detail: `Efficiency ${efficiencyPct}% below budget ${minPct}%.` }
-    : { name: 'min-efficiency', status: 'pass', detail: `Efficiency ${efficiencyPct}% meets budget ${minPct}%.` };
+  const busyCorePct = 100 - model.wastagePct;
+  return busyCorePct < minPct
+    ? { name: 'min-efficiency', status: 'violation', detail: `Busy core time ${busyCorePct}% below budget ${minPct}%.` }
+    : { name: 'min-efficiency', status: 'pass', detail: `Busy core time ${busyCorePct}% meets budget ${minPct}%.` };
 }
 
 function checkRegression(comparison                   , maxRegressionPct        , regressionMetric        )               {
   const row = comparison.metrics.find((m) => m.key === regressionMetric);
   if (!row || row.direction === 'unavailable' || row.baseline == null || row.delta == null) {
-    return { name: 'max-regression', status: 'inconclusive', detail: `Metric "${regressionMetric}" is unavailable for this comparison.` };
+    return { name: 'max-regression', metric: regressionMetric, status: 'inconclusive', detail: `Metric "${regressionMetric}" is unavailable for this comparison.` };
   }
   // A neutral-direction metric (inputBytes/outputBytes/taskCount/executorsAdded) measures
   // workload volume, not performance: an increase isn't a regression, so no direction to check.
   if (row.direction === 'neutral') {
-    return { name: 'max-regression', status: 'inconclusive', detail: `Metric "${regressionMetric}" measures workload volume, not performance: it has no regression direction to check.` };
+    return { name: 'max-regression', metric: regressionMetric, status: 'inconclusive', detail: `Metric "${regressionMetric}" measures workload volume, not performance: it has no regression direction to check.` };
   }
   if (row.direction !== 'regression') {
-    return { name: 'max-regression', status: 'pass', detail: `Metric "${regressionMetric}" did not regress (${row.direction}).` };
+    return { name: 'max-regression', metric: regressionMetric, status: 'pass', detail: `Metric "${regressionMetric}" did not regress (${row.direction}).` };
   }
   const pct = row.baseline === 0 ? Infinity : Math.abs(row.delta / row.baseline) * 100;
   const pctLabel = row.baseline === 0
     ? `regressed from 0 to ${row.delta} (was absent/zero in baseline)`
     : `regressed ${pct.toFixed(1)}%`;
   return pct > maxRegressionPct
-    ? { name: 'max-regression', status: 'violation', detail: `Metric "${regressionMetric}" ${pctLabel}, exceeding budget ${maxRegressionPct}%.` }
-    : { name: 'max-regression', status: 'pass', detail: `Metric "${regressionMetric}" ${pctLabel}, within budget ${maxRegressionPct}%.` };
+    ? { name: 'max-regression', metric: regressionMetric, status: 'violation', detail: `Metric "${regressionMetric}" ${pctLabel}, exceeding budget ${maxRegressionPct}%.` }
+    : { name: 'max-regression', metric: regressionMetric, status: 'pass', detail: `Metric "${regressionMetric}" ${pctLabel}, within budget ${maxRegressionPct}%.` };
 }
 
 function checkFailOnIntroduced(comparison                   , band        )               {
@@ -154,33 +164,50 @@ function pushComparisonBudget(
   comparison                               ,
   name                      ,
   check                                                 ,
+  metric         ,
 )       {
-  results.push(comparison ? check(comparison) : { name, status: 'inconclusive', detail: 'No baseline comparison available to evaluate this budget.' });
+  results.push(comparison ? check(comparison) : {
+    name, status: 'inconclusive', detail: 'No baseline comparison available to evaluate this budget.',
+    ...(metric !== undefined ? { metric } : {}),
+  });
 }
 
-export function evaluateBudgets({ appModel, catalog, budgets, comparison }   
+/** `thresholds`: the overrides the catalog was analyzed with, so a budget that recomputes a
+ * detector's figure (--max-skew) uses the same thresholds. */
+export function evaluateBudgets({ appModel, catalog, budgets, comparison, thresholds }   
                                                                                                  
+                                  
  )                                                                        {
   const results                 = [];
   if (Number.isFinite(budgets.maxRuntimeMs)) results.push(checkRuntime(appModel, budgets.maxRuntimeMs ));
   if (Number.isFinite(budgets.maxSpillGb)) results.push(checkSpill(appModel, catalog, budgets.maxSpillGb ));
-  if (Number.isFinite(budgets.maxSkewRatio)) results.push(checkSkew(appModel, budgets.maxSkewRatio ));
+  if (Number.isFinite(budgets.maxSkewRatio)) results.push(checkSkew(appModel, budgets.maxSkewRatio , skewMinTasksForP95(thresholds)));
   if (Number.isFinite(budgets.maxFailedTaskRatePct)) results.push(checkFailedTaskRate(appModel, catalog, budgets.maxFailedTaskRatePct ));
   if (Number.isFinite(budgets.minEfficiencyPct)) results.push(checkEfficiency(appModel, budgets.minEfficiencyPct ));
   // Guarded here so any evaluateBudgets caller benefits: regressionMetric without
   // maxRegressionPct would otherwise skip the `if` silently, reporting nothing.
   if (budgets.regressionMetric !== undefined && budgets.maxRegressionPct === undefined) {
-    results.push({ name: 'max-regression', status: 'inconclusive', detail: `regressionMetric "${budgets.regressionMetric}" was set without maxRegressionPct; the regression budget was not evaluated.` });
+    results.push({ name: 'max-regression', metric: budgets.regressionMetric, status: 'inconclusive', detail: `regressionMetric "${budgets.regressionMetric}" was set without maxRegressionPct; the regression budget was not evaluated.` });
   } else if (budgets.maxRegressionPct !== undefined) {
     // `!== undefined`, not Number.isFinite: a zero-baseline regression's pct is Infinity,
     // so an "unlimited" budget is a legitimate input (the CLI already rejects non-finite flags).
     pushComparisonBudget(results, comparison, 'max-regression',
-      (c) => checkRegression(c, budgets.maxRegressionPct , budgets.regressionMetric ?? 'wallClock'));
+      (c) => checkRegression(c, budgets.maxRegressionPct , budgets.regressionMetric ?? 'wallClock'),
+      budgets.regressionMetric ?? 'wallClock');
+  }
+  for (const { metric, maxPct } of budgets.regressionBudgets ?? []) {
+    pushComparisonBudget(results, comparison, 'max-regression', (c) => checkRegression(c, maxPct, metric), metric);
   }
   if (budgets.failOnIntroduced !== undefined) {
     pushComparisonBudget(results, comparison, 'fail-on-introduced',
       (c) => checkFailOnIntroduced(c, budgets.failOnIntroduced ));
   }
+  // Always checked, unlike the opt-in budgets above: a run with no ApplicationEnd is
+  // inconclusive by default, so a passing budget can't hide a truncated log.
+  const incompleteRunFinding = catalog.find((f) => f.type === 'incompleteRun');
+  if (incompleteRunFinding) {
+    results.push({ name: 'run-complete', status: 'inconclusive', detail: incompleteRunFinding.recommendation ?? 'Event log has no ApplicationEnd event.' });
+  }
   return {
     results,
     violated: results.some((r) => r.status === 'violation'),

package/vendor-core/cli/collect-run.js

@@ -1,15 +1,19 @@
-import { readFileSync, readdirSync, statSync, openSync, readSync, closeSync } from 'node:fs';
+import { readdirSync, statSync, openSync, readSync, closeSync } from 'node:fs';
 import { join, basename } from 'node:path';
 import { createState, runParse, runParseFiles, reassembleRollingEntries } from '../parser-worker.js';
 import { nodeParseCodecs } from './native-zstd.js';
 import { createModelCallbacks } from '../model-assembler.js';
 import { routeMessage,                     } from '../ingest.js';
                                             
+import { mcpError } from '../mcp-error.js';
 
+// No whole-file arrayBuffer(): the parser only ever reads bounded slices, and a
+// whole-file read is what capped local logs at 2 GiB.
                            
                              
                                                                              
-                                      
+                                                                                   
+                
  
 
 export function emptyAppModel()           {
@@ -24,18 +28,48 @@ export function emptyAppModel()           {
   };
 }
 
-// File-like shape runParse/runParseFiles need: name, size, slice().arrayBuffer(), arrayBuffer().
+// File-like shape runParse/runParseFiles need (name, size, slice().arrayBuffer()), read with
+// positioned readSync so only the requested slice is ever in memory, whatever the file size.
+// The descriptor opens on the first read and closes once a read reaches the end of the file,
+// so a rolling directory's parts hold at most one open descriptor at a time while streaming.
+// A later read (a zip archive reads its tail first) reopens it; callers must still call
+// close() once parsing settles, to cover reads that stopped early on an error.
 export function nodeFileFromPath(path        )           {
-  const bytes = readFileSync(path);
-  const u8 = new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const name = basename(path);
+  const size = statSync(path).size;
+  let fd                = null;
+  const close = () => {
+    if (fd === null) return;
+    const open = fd;
+    fd = null;
+    closeSync(open);
+  };
   return {
-    name: basename(path),
-    size: u8.length,
+    name,
+    size,
     slice(start        , end        ) {
-      const view = u8.subarray(start, end);
-      return { async arrayBuffer() { return view.slice().buffer; } };
+      return {
+        async arrayBuffer()                       {
+          const from = Math.max(0, start);
+          const to = Math.min(end, size);
+          if (to <= from) return new ArrayBuffer(0);
+          const buf = new Uint8Array(to - from);
+          fd ??= openSync(path, 'r');
+          // readSync may return fewer bytes than asked; loop until the slice is full.
+          for (let filled = 0; filled < buf.length;) {
+            const n = readSync(fd, buf, filled, buf.length - filled, from + filled);
+            if (n === 0) {
+              close();
+              throw new Error(`"${name}" shrank while it was being read`);
+            }
+            filled += n;
+          }
+          if (to === size) close();
+          return buf.buffer;
+        },
+      };
     },
-    async arrayBuffer() { return u8.slice().buffer; },
+    close,
   };
 }
 
@@ -96,7 +130,10 @@ export function collectViaDispatch(
   return new Promise((resolve, reject) => {
     const handlers                 = {
       ...cb,
-      onDone: (msg         ) => resolve({ appModel, skippedLines: (msg                             )?.skippedLines ?? 0 }),
+      onDone: (msg         ) => {
+        cb.onDone(msg); // records the parse gaps on the model, as the dashboard's ingest does
+        resolve({ appModel, skippedLines: (msg                             )?.skippedLines ?? 0 });
+      },
       onError: (msg         ) => reject(onDecodeError(msg)),
     };
     const emit = (msg         ) => dispatch(msg, handlers);
@@ -107,26 +144,41 @@ export function collectViaDispatch(
 
 export async function collectRun(inputPath        )                                                        {
   const stat = statSync(inputPath);
-  return collectViaDispatch((state, emit, reject) => {
-    if (stat.isDirectory()) {
-      if (!isRollingLogDirectory(inputPath)) {
-        reject(new Error("This isn't a Spark rolling event-log directory. Pass a single event-log file instead."));
-        return;
-      }
-      const names = readdirSync(inputPath);
-      let ordered;
-      try {
-        ordered = reassembleRollingEntries(names);
-      } catch (e) {
-        reject(e);
-        return;
+  // Every file opened for this run, closed once parsing settles on any path (done, parse
+  // error, decode error, or a throw past the parser's guards).
+  const opened             = [];
+  const open = (path        ) => {
+    const file = nodeFileFromPath(path);
+    opened.push(file);
+    return file;
+  };
+  try {
+    // A file or folder that isn't a decodable event log rejects with invalid-event-log, the code
+    // shs-load.ts gives an archive that fails to decode, so MCP reports both the same way. The
+    // CLI reads only the message.
+    return await collectViaDispatch((state, emit, reject) => {
+      if (stat.isDirectory()) {
+        if (!isRollingLogDirectory(inputPath)) {
+          reject(mcpError('invalid-event-log', "This isn't a Spark rolling event-log directory. Pass a single event-log file instead."));
+          return;
+        }
+        const names = readdirSync(inputPath);
+        let ordered;
+        try {
+          ordered = reassembleRollingEntries(names);
+        } catch (e) {
+          reject(mcpError('invalid-event-log', (e         ).message));
+          return;
+        }
+        const files = ordered.map((name) => open(join(inputPath, name)));
+        // .catch(reject), not void: a throw past the parser's guards would otherwise leave
+        // this Promise pending forever, surfacing only as an unhandled rejection.
+        runParseFiles(files, state, { emit, ...nodeParseCodecs }).catch(reject);
+      } else {
+        runParse(open(inputPath), state, { emit, ...nodeParseCodecs }).catch(reject);
       }
-      const files = ordered.map((name) => nodeFileFromPath(join(inputPath, name)));
-      // .catch(reject), not void: a throw past the parser's guards would otherwise leave
-      // this Promise pending forever, surfacing only as an unhandled rejection.
-      runParseFiles(files, state, { emit, ...nodeParseCodecs }).catch(reject);
-    } else {
-      runParse(nodeFileFromPath(inputPath), state, { emit, ...nodeParseCodecs }).catch(reject);
-    }
-  }, (msg) => new Error((msg                       ).message));
+    }, (msg) => mcpError('invalid-event-log', (msg                       ).message));
+  } finally {
+    for (const file of opened) file.close();
+  }
 }

package/vendor-core/cli/regression-budgets.js

@@ -0,0 +1,83 @@
+// Parses the regression budgets a CLI caller lists: repeated `--regression-budget <metric>:<pct>`
+// flags and a `--budgets <file.json>` file. Every failure throws an Error naming the problem, so
+// the caller refuses to run (exit 2) instead of quietly dropping a budget the user meant to gate on.
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { COMPARISON_METRIC_KEYS } from '../run-comparison.js';
+
+                                                                     
+                                                                                     
+
+// Plain non-negative decimals only: Number() would also accept '', ' ', '0x10' and '1e3'.
+const PCT_PATTERN = /^\d+(\.\d+)?$/;
+
+function assertKnownMetric(metric        , origin        )       {
+  if (!COMPARISON_METRIC_KEYS.includes(metric)) {
+    throw new Error(`${origin}: unknown metric "${metric}" (expected one of: ${COMPARISON_METRIC_KEYS.join(', ')}).`);
+  }
+}
+
+/** One `--regression-budget` value, `<metric>:<pct>`. */
+export function parseRegressionBudgetFlag(spec        )                   {
+  const origin = `--regression-budget "${spec}"`;
+  const colon = spec.indexOf(':');
+  if (colon === -1) throw new Error(`${origin}: expected <metric>:<pct>.`);
+  const metric = spec.slice(0, colon);
+  const pct = spec.slice(colon + 1);
+  assertKnownMetric(metric, origin);
+  if (!PCT_PATTERN.test(pct)) throw new Error(`${origin}: "${pct}" is not a non-negative percentage.`);
+  return { metric, maxPct: Number(pct) };
+}
+
+/** The parsed `--budgets` JSON: `{"regression": {"<metric>": <pct>}}`. */
+export function parseBudgetsFile(raw         , origin        )                     {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new Error(`${origin}: expected a JSON object like {"regression": {"wallClock": 10}}.`);
+  }
+  const unknownKeys = Object.keys(raw).filter((k) => k !== 'regression');
+  if (unknownKeys.length > 0) {
+    throw new Error(`${origin}: unknown key ${unknownKeys.map((k) => `"${k}"`).join(', ')} (the only key is "regression").`);
+  }
+  const regression = (raw                            ).regression;
+  if (regression === null || typeof regression !== 'object' || Array.isArray(regression)) {
+    throw new Error(`${origin}: "regression" must be an object mapping a metric key to a percentage.`);
+  }
+  return Object.entries(regression).map(([metric, pct]) => {
+    assertKnownMetric(metric, origin);
+    if (typeof pct !== 'number' || !Number.isFinite(pct) || pct < 0) {
+      throw new Error(`${origin}: "${metric}" must be a non-negative number (a percentage), got ${JSON.stringify(pct)}.`);
+    }
+    return { metric, maxPct: pct };
+  });
+}
+
+export function loadBudgetsFile(path        )                     {
+  const fullPath = resolve(path);
+  let text        ;
+  try {
+    text = readFileSync(fullPath, 'utf8');
+  } catch (e) {
+    throw new Error(`Cannot read budgets file ${fullPath}: ${(e         ).message}`, { cause: e });
+  }
+  let raw         ;
+  try {
+    raw = JSON.parse(text);
+  } catch (e) {
+    throw new Error(`Budgets file ${fullPath} is not valid JSON: ${(e         ).message}`, { cause: e });
+  }
+  return parseBudgetsFile(raw, `Budgets file ${fullPath}`);
+}
+
+/** Checks that no metric is budgeted twice across the sources (the legacy
+ * `--max-regression-pct`/`--regression-metric` pair counts as one), and returns the budgets. */
+export function combineRegressionBudgets(sources                          )                     {
+  const seen = new Map                ();
+  for (const { origin, budget } of sources) {
+    const first = seen.get(budget.metric);
+    if (first !== undefined) {
+      throw new Error(`Metric "${budget.metric}" has two regression budgets (${first} and ${origin}); give each metric one.`);
+    }
+    seen.set(budget.metric, origin);
+  }
+  return sources.map((s) => s.budget);
+}

package/vendor-core/cli/threshold-config.js

@@ -0,0 +1,28 @@
+// Reads a --thresholds config file for the CLI and the MCP server. Every failure throws an Error
+// naming the file and the problem, so the caller refuses to run instead of quietly falling back
+// to the defaults the user meant to change.
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parseThresholdOverrides } from '../threshold-overrides.js';
+                                                          
+
+export function loadThresholdOverrides(path        )                     {
+  const fullPath = resolve(path);
+  let text        ;
+  try {
+    text = readFileSync(fullPath, 'utf8');
+  } catch (e) {
+    throw new Error(`Cannot read thresholds file ${fullPath}: ${(e         ).message}`, { cause: e });
+  }
+  let raw         ;
+  try {
+    raw = JSON.parse(text);
+  } catch (e) {
+    throw new Error(`Thresholds file ${fullPath} is not valid JSON: ${(e         ).message}`, { cause: e });
+  }
+  try {
+    return parseThresholdOverrides(raw);
+  } catch (e) {
+    throw new Error(`Thresholds file ${fullPath}: ${(e         ).message}`, { cause: e });
+  }
+}

package/vendor-core/comparison-verdict.js

@@ -0,0 +1,177 @@
+import { formatDuration, typeTag } from './format-utils.js';
+import { TAG_HELP } from './finding-tag-help.js';
+import { NEUTRAL_METRIC_KEYS,                        } from './run-comparison.js';
+
+/** The slice of a comparison metric row the verdict reads. */
+                                
+              
+                
+                          
+                           
+                       
+                                                                                    
+ 
+
+/** The slice of a finding-category delta the verdict reads. */
+                                  
+               
+                    
+                    
+ 
+
+/** How many of a run's ended jobs failed, counted as `summarizeRunOutcome`
+ * counts them. */
+                                    
+                     
+                    
+                                                                            
+                               
+                       
+ 
+
+                                                                     
+
+                                        
+                
+                       
+                      
+ 
+
+/** A change under this share of the baseline's value reads as "about the same", for
+ * run time and cost metrics alike: run-to-run noise on a shared cluster easily
+ * moves a job a percent or two. */
+export const SAME_CHANGE_SHARE = 0.02;
+
+function measured(metric               )                                                                    {
+  return metric.baseline != null && metric.candidate != null;
+}
+
+function movedPastNoise(metric                                                         )          {
+  if (metric.baseline === 0) return metric.candidate !== 0;
+  return Math.abs(metric.candidate - metric.baseline) / Math.abs(metric.baseline) >= SAME_CHANGE_SHARE;
+}
+
+/** Plain name for a finding type ("Memory and disk spill"), falling back to
+ * its tag when the tag has no help entry. */
+function categoryName(type        )         {
+  const tag = typeTag(type);
+  return TAG_HELP[tag]?.expansion ?? tag;
+}
+
+/** Net count change per displayed category name. Categories are tallied per
+ * (rule, impact band), and several rules share one name (every Plan Advisor
+ * type reads "Plan advisor", every stage-shape sub-rule "Stage shape"), so a
+ * rule whose findings moved from critical to warning, or two rules under one
+ * name moving opposite ways, would otherwise
+ * read as both "introduced" and "resolved". Order follows first appearance,
+ * introduced before resolved. */
+function netByCategory(findings                                                                )                      {
+  const net = new Map                ();
+  for (const item of [...findings.introduced, ...findings.resolved]) {
+    const name = categoryName(item.type);
+    net.set(name, (net.get(name) ?? 0) + item.candCount - item.baseCount);
+  }
+  return net;
+}
+
+function namesWhere(net                     , keep                             )           {
+  return [...net].filter(([, change]) => keep(change)).map(([name]) => name);
+}
+
+/** "The candidate had 2 of 5 jobs fail", or, when every job failed, "The candidate's only
+ * job failed" / "All 3 of the candidate's jobs failed" rather than "1 of 1 jobs". */
+function jobsFailed(run                          , { failedJobs, totalJobs }                   )         {
+  if (failedJobs < totalJobs) return `The ${run} had ${failedJobs} of ${totalJobs} jobs fail`;
+  return totalJobs === 1 ? `The ${run}'s only job failed` : `All ${totalJobs} of the ${run}'s jobs failed`;
+}
+
+/** The baseline's failures in the parenthesis after the candidate's. */
+function baselineFailures({ failedJobs, totalJobs }                   )         {
+  if (failedJobs === 0) return 'none';
+  if (failedJobs < totalJobs) return `${failedJobs} of ${totalJobs}`;
+  return totalJobs === 1 ? 'its only job failed' : `all ${totalJobs} failed`;
+}
+
+/** The headline when either run had failed jobs, as the run verdict leads
+ * with a failure: a faster candidate that dropped work is not an improvement,
+ * and with equal failure counts the tone stays neutral since a failing run
+ * that ends sooner may just have failed earlier. Null when both runs
+ * completed. */
+function failureHeadline(base                   , cand                   )                                                 {
+  if (base.failedJobs === 0 && cand.failedJobs === 0) return null;
+  const tone = cand.failedJobs > base.failedJobs ? 'worse' : cand.failedJobs < base.failedJobs ? 'better' : 'same';
+  if (cand.failedJobs === 0) return { title: `${jobsFailed('baseline', base)}; the candidate completed`, tone };
+  return { title: `${jobsFailed('candidate', cand)} (baseline: ${baselineFailures(base)})`, tone };
+}
+
+/** One plain answer to "did the candidate get better or worse than the baseline", from the
+ * comparison's own whole-run metrics and finding-category tallies: run time
+ * first, then which cost metrics moved each way past run-to-run noise, then which finding
+ * categories appeared or went away. When either run had failed jobs, that
+ * leads instead and run time becomes the first sentence. When either log is
+ * incomplete, run time is stated as what each log covers, never as faster or
+ * slower, and the tone stays neutral. Volume and count metrics (input, output,
+ * tasks, executors) are left out because more or less of them is not
+ * inherently better or worse. */
+export function summarizeComparison(
+  metrics                 ,
+  findings                                                                ,
+  jobs                                                                ,
+)                        {
+  const wall = metrics.find((metric) => metric.key === 'wallClock');
+  let title = 'Run time could not be compared between the baseline and the candidate';
+  let tone                 = 'unknown';
+  // A log with no end-of-run record stops where the run was cut off, so its
+  // shorter time is not a speed-up: say how much each log covers, neutrally.
+  const incompleteRuns = jobs ? (['baseline', 'candidate']         ).filter((run) => jobs[run].incomplete) : [];
+  if (wall && wall.baseline != null && wall.baseline > 0 && wall.candidate != null && incompleteRuns.length > 0) {
+    const change = wall.candidate - wall.baseline;
+    title = Math.abs(change / wall.baseline) < SAME_CHANGE_SHARE
+      ? "The candidate's log covers about as much run time as the baseline's"
+      : `The candidate's log covers ${formatDuration(Math.abs(change))} ${change < 0 ? 'less' : 'more'} run time than the baseline's`;
+  } else if (wall && wall.baseline != null && wall.baseline > 0 && wall.candidate != null) {
+    const change = wall.candidate - wall.baseline;
+    const share = change / wall.baseline;
+    if (Math.abs(share) < SAME_CHANGE_SHARE) {
+      title = 'The candidate took about as long as the baseline';
+      tone = 'same';
+    } else {
+      const faster = change < 0;
+      title = `The candidate finished ${formatDuration(Math.abs(change))} ${faster ? 'faster' : 'slower'} than the baseline (${Math.round(Math.abs(share) * 100)}%)`;
+      tone = faster ? 'better' : 'worse';
+    }
+  }
+
+  const cost = metrics.filter((metric) => metric.key !== 'wallClock' && !NEUTRAL_METRIC_KEYS.has(metric.key)).filter(measured);
+  const moved = cost.filter(movedPastNoise);
+  const worse = moved.filter((metric) => metric.direction === 'regression').map((metric) => metric.label);
+  const better = moved.filter((metric) => metric.direction === 'improvement').map((metric) => metric.label);
+  const sentences           = [];
+  const failure = jobs ? failureHeadline(jobs.baseline, jobs.candidate) : null;
+  if (failure) {
+    sentences.push(`${title}.`);
+    title = failure.title;
+    tone = failure.tone;
+  }
+  if (incompleteRuns.length === 2) {
+    sentences.push('Neither log has an end-of-run record, so their times cover only what each log captured, not how long the runs took.');
+  } else if (incompleteRuns.length === 1) {
+    sentences.push(`The ${incompleteRuns[0]}'s log has no end-of-run record, so its time covers only what the log captured, not how long the run took.`);
+  }
+  if (worse.length > 0) sentences.push(`Worse in the candidate: ${worse.join(', ')}.`);
+  if (better.length > 0) sentences.push(`Better in the candidate: ${better.join(', ')}.`);
+  if (cost.length > 0 && worse.length === 0 && better.length === 0) sentences.push('Other measured cost metrics look about the same.');
+
+  const net = netByCategory(findings);
+  const introduced = namesWhere(net, (change) => change > 0);
+  const resolved = namesWhere(net, (change) => change < 0);
+  if (introduced.length > 0) sentences.push(`New or more frequent in the candidate: ${introduced.join(', ')}.`);
+  if (resolved.length > 0) sentences.push(`Less frequent in the candidate: ${resolved.join(', ')}.`);
+  return { title, tone, sentences };
+}
+
+/** The comparison verdict for a core comparison result: the one the dashboard's comparison page
+ * leads with, and the one the CLI's --baseline report and MCP compare_runs carry. */
+export function comparisonVerdict(result                                                                 )                        {
+  return summarizeComparison(result.metrics, result.findings, result.jobOutcomes);
+}

package/vendor-core/core-source-hash.txt

@@ -0,0 +1 @@
+ab36c5fdcdc1a32a4e6206459e843e8d2267a90e6f1de29671827315d81bc374