sparkforensics-server 0.4.0 → 0.5.1

package/public/index.html

@@ -23,12 +23,12 @@
           document.documentElement.setAttribute('data-theme', 'light');
       } catch (_) {}
     </script>
-    <script type="module" crossorigin src="./assets/index-CEM9bz_x.js"></script>
+    <script type="module" crossorigin src="./assets/index-DCeWge12.js"></script>
     <link rel="modulepreload" crossorigin href="./assets/rolldown-runtime-hePW80VL.js">
     <link rel="modulepreload" crossorigin href="./assets/charts-vendor-0VMaLVLN.js">
-    <link rel="modulepreload" crossorigin href="./assets/plan-graph-vendor-B0sEms9Z.js">
-    <link rel="modulepreload" crossorigin href="./assets/react-vendor-BAKt3vny.js">
-    <link rel="modulepreload" crossorigin href="./assets/DisclosureContext-LYzHroHO.js">
+    <link rel="modulepreload" crossorigin href="./assets/plan-graph-vendor-BYl-AzN5.js">
+    <link rel="modulepreload" crossorigin href="./assets/react-vendor-DEdfrRTJ.js">
+    <link rel="modulepreload" crossorigin href="./assets/DisclosureContext-B0siMVdg.js">
     <link rel="stylesheet" crossorigin href="./assets/plan-graph-vendor-DLioOiRN.css">
     <link rel="stylesheet" crossorigin href="./assets/index-BcqTLKFp.css">
   </head>

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/caveats-tuning-and-coverage.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/api-merge-writes.js

@@ -0,0 +1,80 @@
+// DeltaTable API merges run no command node: each internal query is its own root execution, tied
+// together only by a "MERGE operation" description and adjacent ids. One DeltaMerge write is
+// reported per run of such executions, with a path only when no other merge can be mixed into it.
+import { soleLogPath } from './delta-log-paths.js';
+                                               
+                                                      
+
+                                                                                                              
+
+const API_MERGE_COMMAND = 'DeltaMerge';
+
+// Delta labels its MERGE sub-queries "MERGE operation - <phase>", prefixed "Delta: " in some.
+const MERGE_DESCRIPTION = /^(?:Delta: )?MERGE operation\b/;
+
+// The sub-queries that write: "writing new files ...", "Rewriting N files". A group without one
+// only scanned, and a scan may read the merge's source rather than its target.
+const MERGE_WRITE_PHASE = /\b(?:re)?writing\b/i;
+
+                                                                          
+
+// Selected executions have a MERGE description. A SQL MERGE's own sub-queries carry the same
+// description but belong to the MergeIntoCommand execution they share a root with, which is
+// attributed through its own node (resolveDeltaCommandTarget), so they are left out. A sub-query
+// of an API merge may have another of its executions as its root, so a root alone does not exclude.
+function selectMergeExecutions(sql                             )                   {
+  const isSqlMergeRoot = (id                    )          =>
+    id !== undefined && /^Execute\s+MergeIntoCommand\b/.test(sql.get(id)?.planTree?.name ?? '');
+  return [...sql.values()]
+    .filter((exec) => MERGE_DESCRIPTION.test(exec.description ?? '') && !isSqlMergeRoot(exec.rootExecutionId))
+    .sort((a, b) => a.id - b.id);
+}
+
+// A run of consecutive execution ids. Nothing in the log ties the members of one merge together,
+// so adjacency is a guess, and a wrong one fuses or splits merges. Each way it can go wrong is
+// marked `unclean` instead of attributed:
+//   - the ids of two merges that ran concurrently interleave, so their start-time spans overlap;
+//   - a start time is missing, so the span is unknown.
+//   - no member writes, so the one path it names may be a source's.
+// Merges that ran back to back with no other execution between them still fuse into one run; the
+// run then names two paths and gets no target.
+function groupMerges(selected                  )               {
+  const groups               = [];
+  for (const exec of selected) {
+    const last = groups[groups.length - 1];
+    if (last && last.members[last.members.length - 1].id + 1 === exec.id) last.members.push(exec);
+    else groups.push({ members: [exec], unclean: null });
+  }
+  const spans = groups.map(({ members }) => {
+    const starts = members.map((m) => m.startTime);
+    return starts.every((t)              => typeof t === 'number') ? [Math.min(...starts), Math.max(...starts)] : null;
+  });
+  groups.forEach((group, i) => {
+    const mine = spans[i];
+    if (mine === null) { group.unclean = 'start time missing'; return; }
+    const overlaps = spans.some((other, j) => j !== i && other !== null && other[0] <= mine[1] && mine[0] <= other[1]);
+    if (overlaps) group.unclean = 'overlaps another merge in time';
+    else if (!group.members.some((m) => MERGE_WRITE_PHASE.test(m.description ?? ''))) group.unclean = 'no write phase';
+  });
+  return groups;
+}
+
+/** One DeltaMerge write per run of API merge executions; null target unless one path is certain. */
+export function apiMergeWrites(sql                             )                {
+  return groupMerges(selectMergeExecutions(sql)).map((group) => {
+    const first = group.members[0].id;
+    const last = group.members[group.members.length - 1].id;
+    const resolved = group.unclean === null ? soleLogPath(group.members) : null;
+    const span = first === last ? `${first}` : `${first}-${last}`;
+    return {
+      sqlExecutionId: first,
+      nodeId: null,
+      command: API_MERGE_COMMAND,
+      recognized: true,
+      kind: resolved?.kind ?? null,
+      target: resolved?.target ?? null,
+      outputRows: null,
+      raw: `Delta MERGE operation, executions ${span}${group.unclean ? ` (${group.unclean})` : ''}`,
+    };
+  });
+}

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-output.js

@@ -0,0 +1,49 @@
+import { buildComparison,                                             } from './run-comparison.js';
+import { comparisonVerdict,                            } from './comparison-verdict.js';
+import { redactComparison } from './redact.js';
+                                                    
+
+                                                                                             
+
+// The comparison a surface reports: the CLI's `comparison` object and the shared part of MCP
+// compare_runs. A field added here reaches every surface.
+// `stagePairs` is the one large field (a row per paired stage), so the `summary` view leaves it out.
+                                                                 
+                           
+                                                                                            
+                                                                                    
+                                                   
+
+/** `full` carries every field (the CLI); `summary` leaves out `stagePairs` (MCP, which returns them
+ * only when asked). */
+                                                
+
+/** The reported projection of a comparison. Key order is the CLI's JSON order. */
+export function comparisonOutput(comparison                   , view                 = 'full')                   {
+  return {
+    verdict: comparisonVerdict(comparison),
+    confidence: comparison.confidence,
+    reason: comparison.reason,
+    matchedCoverage: comparison.matchedCoverage,
+    runtimeCoverage: comparison.runtimeCoverage,
+    metrics: comparison.metrics,
+    findings: comparison.findings,
+    comparisonSchemaVersion: comparison.comparisonSchemaVersion,
+    ...(view === 'full' ? { stagePairs: comparison.stagePairs } : {}),
+    unmatched: comparison.unmatched,
+    replanned: comparison.replanned,
+    bookkeepingStageIds: comparison.bookkeepingStageIds,
+  };
+}
+
+/** Diffs the two runs and applies `redact` here, so no surface can skip it (stage names carry raw
+ * Spark text that can embed a host or IP). `comparison` is the (redacted) raw result for budgets
+ * and Markdown; `output` is the projection to serialize. */
+export function buildComparisonOutput(
+  baseline                    , candidate                    ,
+  { redact, normalizePath, view }                                                               = {},
+)                                                              {
+  const built = buildComparison(baseline, candidate, { normalizePath });
+  const comparison = redact ? redactComparison(built) : built;
+  return { comparison, output: comparisonOutput(comparison, view) };
+}