sparkforensics-mcp 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparkforensics-mcp",
-  "version": "0.4.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

@@ -88,32 +88,32 @@ export function findingId(f         )         {
   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(' ');
   }
 }
 
@@ -201,7 +201,7 @@ export function analyze(
   // 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,
+    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

package/vendor-core/cli/budgets.js

@@ -4,6 +4,7 @@ import { effectiveThresholds } from '../threshold-overrides.js';
 import { IMPACT_BAND_ORDER } from '../format-utils.js';
                                                               
                                                                  
+                                                                
 
 const IMPACT_BANDS = Object.keys(IMPACT_BAND_ORDER)                ;
 
@@ -11,12 +12,16 @@ const IMPACT_BANDS = Object.keys(IMPACT_BAND_ORDER)                ;
                                                                     
                                                            
                                                                                   
+                                                                                                 
+                                         
  
                                
                                                                                             
                                                                
                                                 
                  
+                                                                            
+                  
  
 
 // The skew entry's minTasksForP95 under the run's overrides, so the budget measures the same
@@ -107,7 +112,8 @@ function checkEfficiency(appModel          , minPct        )               {
   }
   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: 'Busy core time could not be computed (no available compute hours).' };
@@ -121,23 +127,23 @@ function checkEfficiency(appModel          , 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        )               {
@@ -158,8 +164,12 @@ 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 } : {}),
+  });
 }
 
 /** `thresholds`: the overrides the catalog was analyzed with, so a budget that recomputes a
@@ -177,12 +187,16 @@ export function evaluateBudgets({ appModel, catalog, budgets, comparison, thresh
   // 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',

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

@@ -5,6 +5,7 @@ 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.
@@ -129,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);
@@ -149,10 +153,13 @@ export async function collectRun(inputPath        )
     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(new Error("This isn't a Spark rolling event-log directory. Pass a single event-log file instead."));
+          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);
@@ -160,7 +167,7 @@ export async function collectRun(inputPath        )
         try {
           ordered = reassembleRollingEntries(names);
         } catch (e) {
-          reject(e);
+          reject(mcpError('invalid-event-log', (e         ).message));
           return;
         }
         const files = ordered.map((name) => open(join(inputPath, name)));
@@ -170,7 +177,7 @@ export async function collectRun(inputPath        )
       } else {
         runParse(open(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/comparison-verdict.js

@@ -37,7 +37,7 @@ import { NEUTRAL_METRIC_KEYS,                        } from './run-comparison.js
                       
  
 
-/** A change under this share of run A's value reads as "about the same", for
+/** 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;
@@ -78,14 +78,14 @@ function namesWhere(net                     , keep                             )
   return [...net].filter(([, change]) => keep(change)).map(([name]) => name);
 }
 
-/** "Run B had 2 of 5 jobs fail", or, when every job failed, "Run B's only
- * job failed" / "All 3 of run B's jobs failed" rather than "1 of 1 jobs". */
-function jobsFailed(run           , { failedJobs, totalJobs }                   )         {
-  if (failedJobs < totalJobs) return `Run ${run} had ${failedJobs} of ${totalJobs} jobs fail`;
-  return totalJobs === 1 ? `Run ${run}'s only job failed` : `All ${totalJobs} of run ${run}'s jobs failed`;
+/** "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`;
 }
 
-/** Run A's failures in the parenthesis after run B's. */
+/** 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}`;
@@ -93,18 +93,18 @@ function baselineFailures({ failedJobs, totalJobs }                   )
 }
 
 /** The headline when either run had failed jobs, as the run verdict leads
- * with a failure: a faster run B that dropped work is not an improvement,
+ * 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('A', base)}; run B completed`, tone };
-  return { title: `${jobsFailed('B', cand)} (run A: ${baselineFailures(base)})`, tone };
+  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 run B get better or worse than run A", from the
+/** 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
@@ -119,25 +119,25 @@ export function summarizeComparison(
   jobs                                                                ,
 )                        {
   const wall = metrics.find((metric) => metric.key === 'wallClock');
-  let title = 'Run time could not be compared between run A and run B';
+  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 ? (['A', 'B']         ).filter((run) => (run === 'A' ? jobs.baseline : jobs.candidate).incomplete) : [];
+  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
-      ? "Run B's log covers about as much run time as run A's"
-      : `Run B's log covers ${formatDuration(Math.abs(change))} ${change < 0 ? 'less' : 'more'} run time than run A's`;
+      ? "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 = 'Run B took about as long as run A';
+      title = 'The candidate took about as long as the baseline';
       tone = 'same';
     } else {
       const faster = change < 0;
-      title = `Run B finished ${formatDuration(Math.abs(change))} ${faster ? 'faster' : 'slower'} than run A (${Math.round(Math.abs(share) * 100)}%)`;
+      title = `The candidate finished ${formatDuration(Math.abs(change))} ${faster ? 'faster' : 'slower'} than the baseline (${Math.round(Math.abs(share) * 100)}%)`;
       tone = faster ? 'better' : 'worse';
     }
   }
@@ -156,17 +156,17 @@ export function summarizeComparison(
   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(`Run ${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.`);
+    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 run B: ${worse.join(', ')}.`);
-  if (better.length > 0) sentences.push(`Better in run B: ${better.join(', ')}.`);
+  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 run B: ${introduced.join(', ')}.`);
-  if (resolved.length > 0) sentences.push(`Less frequent in run B: ${resolved.join(', ')}.`);
+  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 };
 }
 

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

@@ -1 +1 @@
-b5b0e0b6178129de4de482d4b59fbf881822655d8911b374c4a60a33b38f63fb
+ab36c5fdcdc1a32a4e6206459e843e8d2267a90e6f1de29671827315d81bc374