sparkforensics-server 0.6.0 → 0.8.1

package/vendor-core/html-export.js

@@ -25,7 +25,7 @@ export function buildHtmlExportData(
   skippedLines        ,
   { redact, buildId, producer }                                                        ,
 )                {
-  const raw = { appModel, catalog, configFindings: auditConfig(appModel.app) };
+  const raw = { appModel, catalog, configFindings: auditConfig(appModel.app, appModel.stages) };
   const run = redact ? redactRunModel(raw.appModel, raw.catalog, raw.configFindings) : raw;
   const interpretation = interpretRun(run.appModel, run.catalog, run.configFindings);
   const provenance                   = { coreVersion: CORE_VERSION, buildId, producer };

package/vendor-core/impact-band.js

@@ -1,8 +1,8 @@
                                                         
 
 // The run-wide noise floor, as a share of the run's duration, that grades every wall-clock
-// estimate (NOT SOURCED: our own, unvalidated). skew and straggler default their firing floors to
-// these same figures (detectors.ts), so a finding they admit grades at least warning here.
+// estimate. skew and straggler default their firing floors to these same figures (detectors.ts), so
+// a finding they admit grades at least warning here. Source status: threshold-tables.md.
 export const IMPACT_FLOOR_PCT_WARN = 0.005;
 export const IMPACT_FLOOR_PCT_CRIT = 0.02;
 

package/vendor-core/impact-format.js

@@ -1,18 +1,33 @@
 // Savings figures as every surface prints them: the dashboard's widgets and verdict, and the
 // CLI/MCP evidence report. One formatter set, so units and rounding never drift between paths.
-import { fmtMs, formatRawWaste, formatWallClockRange, readsAsZero } from './format-utils.js';
+// A figure that rounds to zero ("0s", "0.0 core-h") reads as a measured nothing, so every
+// formatter here shows no figure for it (see readsAsZero in format-utils.ts).
+import { asCoreTime, fmtMs, formatRawWaste, formatWallClockRange, readsAsZero } from './format-utils.js';
                                                                           
 
+/** The raw figure as the surfaces print it: a cost-only (`resourceOnly`) task-time figure in core
+ * time, anything else as the detector emitted it. `rawWaste` itself stays untouched. */
+function shownRawWaste(estimate                )                             {
+  const rawWaste = estimate.rawWaste;
+  return rawWaste && estimate.basis === 'resourceOnly' ? asCoreTime(rawWaste) : rawWaste;
+}
+
+/** " (modeled)" after a cost-only figure that rests on an assumed constant, so a modeled core
+ * time never reads as a measured one. Empty for any other estimate. */
+function certaintyNote(estimate                )         {
+  return estimate.basis === 'resourceOnly' && estimate.estimateMethod === 'modeled' ? ' (modeled)' : '';
+}
+
 /** A finding's one-line savings figure: the wall-clock range for a time-based
  * finding, the raw resource figure for a `resourceOnly` one, or nothing for a
- * purely informational estimate or a raw figure that rounds to zero ("0.0
- * core-h" reads as a measured nothing). */
+ * purely informational estimate. */
 export function impactFigure(finding         )                {
   const estimate = finding.impactEstimate;
   if (!estimate) return null;
   if (estimate.wallClock) return formatWallClockRange(estimate.wallClock.low, estimate.wallClock.high);
-  if (estimate.rawWaste) {
-    const text = formatRawWaste(estimate.rawWaste);
+  const rawWaste = shownRawWaste(estimate);
+  if (rawWaste) {
+    const text = formatRawWaste(rawWaste);
     return readsAsZero(text) ? null : text;
   }
   return null;
@@ -25,7 +40,7 @@ export function rawWasteMeaning(rawWaste                            )
     case 'mbSeconds': return 'of unused executor memory';
     case 'coreHours':
     case 'coreMs': return rawWaste.idle ? 'of idle core capacity' : 'of core time';
-    case 'bytes': return 'of extra data written';
+    case 'bytes': return rawWaste.reread ? 'of input read by the repeated scans' : 'of extra data written';
     case 'ms': return 'of task time';
     default: return null;
   }
@@ -40,30 +55,34 @@ export function savingsMeaning(finding         )                {
   const estimate = finding.impactEstimate;
   if (!estimate) return null;
   if (estimate.wallClock) return 'of run time';
-  return rawWasteMeaning(estimate.rawWaste);
+  const meaning = rawWasteMeaning(estimate.rawWaste);
+  return meaning && `${meaning}${certaintyNote(estimate)}`;
 }
 
 /** A finding's "Potential savings" figure as the widget board shows it: the
  * wall-clock range, or the raw waste only when there is no wall-clock claim,
  * never both (they would read as two competing numbers). A zero-value
- * estimate is suppressed like an informational one: "0s" reads as a measured
- * figure. `meaning` says what the shown figure counts. */
+ * estimate is suppressed like an informational one. `meaning` says what the
+ * shown figure counts. */
 export function impactEstimateFigure(estimate                            )                                                  {
   if (!estimate) return null;
   const highText = estimate.wallClock && estimate.wallClock.high > 0 ? fmtMs(estimate.wallClock.high) : null;
   if (highText && !readsAsZero(highText)) {
     return { text: formatWallClockRange(estimate.wallClock .low, estimate.wallClock .high), meaning: 'of run time' };
   }
-  const rawWasteText = estimate.rawWaste && estimate.rawWaste.value > 0 ? formatRawWaste(estimate.rawWaste) : null;
-  if (rawWasteText && !readsAsZero(rawWasteText)) return { text: rawWasteText, meaning: rawWasteMeaning(estimate.rawWaste) };
+  const rawWaste = shownRawWaste(estimate);
+  const rawWasteText = rawWaste && rawWaste.value > 0 ? formatRawWaste(rawWaste) : null;
+  if (rawWasteText && !readsAsZero(rawWasteText)) {
+    const meaning = rawWasteMeaning(estimate.rawWaste);
+    return { text: rawWasteText, meaning: meaning && `${meaning}${certaintyNote(estimate)}` };
+  }
   return null;
 }
 
 /** Compact single-value form for dense lists (the stage table's finding chips,
  * the stage dialog): the high-end wall-clock figure, or the raw-waste figure
  * when there's no wall-clock claim, or `null` for a purely informational or a
- * zero-value estimate (a `0s` in the spot a real estimate goes would read as a
- * measured nothing). */
+ * zero-value estimate. */
 export function impactEstimateCompact(estimate                            )                {
   if (!estimate) return null;
   if (estimate.wallClock) {
@@ -71,10 +90,11 @@ export function impactEstimateCompact(estimate                            )
     const text = fmtMs(estimate.wallClock.high);
     return readsAsZero(text) ? null : text;
   }
-  if (estimate.rawWaste) {
-    if (estimate.rawWaste.value <= 0) return null;
-    const text = formatRawWaste(estimate.rawWaste);
-    return readsAsZero(text) ? null : text;
+  const rawWaste = shownRawWaste(estimate);
+  if (rawWaste) {
+    if (rawWaste.value <= 0) return null;
+    const text = formatRawWaste(rawWaste);
+    return readsAsZero(text) ? null : `${text}${certaintyNote(estimate)}`;
   }
   return null;
 }
@@ -88,14 +108,22 @@ export function impactEstimateCompact(estimate                            )
  * formatting and zero rules as the step's own savings figure, which it does
  * not repeat: the step already shows it. */
 export function estimateProvenance(finding                                 )                {
+  const sentence = provenanceSentence(finding);
+  const assumptions = finding.impactEstimate?.assumptions;
+  if (!sentence || !assumptions) return sentence;
+  return `${sentence} ${assumptions[0].toUpperCase()}${assumptions.slice(1)}.`;
+}
+
+function provenanceSentence(finding                                 )                {
   const estimate = finding.impactEstimate;
   if (!estimate || estimate.estimateMethod === 'none') return null;
   const method = `${estimate.estimateMethod[0].toUpperCase()}${estimate.estimateMethod.slice(1)}`;
-  const rawWaste = estimate.rawWaste && estimate.rawWaste.value > 0 ? estimate.rawWaste : null;
+  const shown = shownRawWaste(estimate);
+  const rawWaste = shown && shown.value > 0 ? shown : null;
   const raw = rawWaste && !readsAsZero(formatRawWaste(rawWaste)) ? formatRawWaste(rawWaste) : null;
   const wallClock = estimate.wallClock;
   if (estimate.basis === 'resourceOnly') {
-    return raw ? `${method}; ${raw} wasted, which may not shorten the run.` : null;
+    return raw ? `${method}; ${raw} ${rawWasteMeaning(estimate.rawWaste) ?? 'wasted'}, which may not shorten the run.` : null;
   }
   if (!wallClock || wallClock.high <= 0) return null;
   const highText = formatWallClockRange(wallClock.high, wallClock.high);

package/vendor-core/impact-model.js

@@ -19,6 +19,10 @@ import {
                      
                                                                                                   
                                   
+                                                                                                  
+                                                                                                 
+                             
+                                
  
 
 // Assumed shuffle-network throughput per executor link, ~1 Gbps. Starting assumption, unvalidated.
@@ -43,10 +47,8 @@ export function measuredTaskOverhead(stage       )
 
 // Both constants above are single-device figures (one NIC, one local disk). A stage's shuffle
 // reads and spills are spread over every executor that ran its tasks, each moving its own share
-// in parallel, so the stage's aggregate bandwidth scales with that executor count. Dividing a
-// stage-wide byte total by one device's bandwidth modeled the whole cluster as one link: on 14
-// real logs that claimed up to 1,870s of shuffle time on stages whose tasks measured ~0s of
-// shuffle fetch wait (222 of 284 shuffle findings). No executor data falls back to one device.
+// in parallel, so the stage's aggregate bandwidth scales with that executor count. No executor
+// data falls back to one device.
 export function stageIoParallelism(stage       )         {
   const executors = Array.isArray(stage.executorStats) ? stage.executorStats.length : 0;
   return Math.max(1, executors);
@@ -55,9 +57,7 @@ export function stageIoParallelism(stage       )         {
 // Wall-clock the stage's tasks spent blocked fetching shuffle blocks: fetchWaitTime is a
 // cross-task sum like executorRunTime, so dividing by the stage's average concurrency converts it
 // (the gc estimate's conversion). Null when the stage has no run time or duration to convert with.
-// On 14 real logs the link model claimed 2780s over 284 shuffle findings, 256s once capped at
-// this, with about zero fetch wait on 5 of the 10 non-info ones: reads that overlapped compute
-// stalled nothing.
+// The link model caps at this because reads that overlap compute stall nothing.
 export function fetchWaitWallClockMs(stage       )                {
   const fetchWaitMs = stage.fetchWaitTime;
   const runTimeMs = stage.executorRunTime ?? 0;
@@ -66,10 +66,9 @@ export function fetchWaitWallClockMs(stage       )                {
   return fetchWaitMs / (runTimeMs / durationMs);
 }
 
-// Wall-clock a stage's wasted (retried) attempts cost it. Each one delayed only its own task, and
-// attempts of different tasks ran side by side: one lost executor fails every task it was running
-// at once (4 wasted attempts of 36.6s each, all first attempts, on a real stage that ran 41 tasks
-// at once, claimed as 146.6s). So the stage lost at most its longest retry chain, the most attempts
+// Wall-clock a stage's wasted (retried) attempts cost it. Each one delays only its own task, and
+// attempts of different tasks run side by side: one lost executor fails every task it was running
+// at once. So the stage loses at most its longest retry chain, the most attempts
 // one task wasted (its highest attempt number + 1) times the mean wasted attempt, or their summed
 // time spread over its slots, whichever is larger. Without a sample of every wasted attempt
 // (retryTaskSamples is capped), the chain isn't known: the summed time.
@@ -99,10 +98,8 @@ export const EXECUTOR_STARTUP_OVERHEAD_MS = 15000;
 // Assumed re-read throughput, shared by cachingOpportunity and cacheUtilization.
 export const RE_READ_THROUGHPUT_BPS = 125_000_000;
 
-// Below this share of executorRunTime spent on CPU, a stage's tasks were idle, waiting on something
-// outside Spark: on 14 real logs (2026-09-23) every non-Python stage under 1% was a JDBC read, a
-// file listing or a Delta log read, while file writes, which more partitions do parallelize,
-// start at 2%.
+// Below this share of executorRunTime spent on CPU, a stage's tasks are idle, waiting on something
+// outside Spark (rationale: impact-estimation/caveats-tuning-and-coverage.md, Idle CPU share).
 const IDLE_CPU_SHARE_MAX = 0.01;
 
 // True when the stage's tasks spent under IDLE_CPU_SHARE_MAX of their run time on CPU. False when
@@ -130,6 +127,20 @@ export function costOnly(estimateMethod                      , rawWaste
     : { basis: 'informational', wallClock: null, estimateMethod };
 }
 
+/** The estimate with what its model assumes and leaves out (`ImpactEstimate.assumptions`). */
+export function withAssumptions(estimate                , assumptions        )                 {
+  return { ...estimate, assumptions };
+}
+
+/** The throughput assumption behind a per-executor I/O model (stageIoParallelism), in the words
+ * `ImpactEstimate.assumptions` carries: the rate and how many executors it was spread over. */
+export function ioModelAssumption(bytesPerSecond        , stage       )         {
+  const executors = Array.isArray(stage.executorStats) ? stage.executorStats.length : 0;
+  const rate = `${Math.round(bytesPerSecond / 1e6)} MB/s`;
+  if (executors === 0) return `assumes ${rate} on one device, as the stage has no per-executor data`;
+  return `assumes ${rate} per executor over ${executors} ${executors === 1 ? 'executor' : 'executors'}`;
+}
+
 /** The estimate() of an entry whose findings have no waste model at all. */
 export function noWasteModel()                 {
   return costOnly('none');

package/vendor-core/job-groups.js

@@ -1,10 +1,10 @@
-// §8 Concurrent-job-group reliability guard. Groups jobs by SQL
-// execution id (jobs with none form singleton groups). If two DIFFERENT groups' intervals overlap,
-// wall-clock-based estimates become unreliable. Jobs WITHIN a group overlapping (AQE) is normal.
+// Concurrent-job-group reliability guard. Groups jobs by SQL execution id (jobs with none form
+// singleton groups). If two DIFFERENT groups' intervals overlap, wall-clock-based estimates become
+// unreliable. Jobs WITHIN a group overlapping (AQE) is normal.
 export function checkConcurrentJobGroups(jobs                                                                                                                             )                                                                        {
   const list = jobs ? [...jobs.values()] : [];
   // Build one interval per group: [min submission, max completion].
-  const groups = new Map(); // key -> { start, end }
+  const groups = new Map();
   let singletonSeq = 0;
   for (const j of list) {
     if (j.submissionTime == null || j.completionTime == null) continue;

package/vendor-core/mcp-server-factory.js

@@ -2,10 +2,12 @@ import { z } from 'zod';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
                                                                          
 import {
-  resolveOrCreateRun, diagnoseRun, getRunSummary, compareRuns, getFindingEvidence, getFindingDocumentation, getReferenceDoc, evaluateBudgetsForRun,
+  resolveOrCreateRun, diagnoseRun, diagnoseHeadline, getRunSummary, compareRuns, getFindingEvidence, getFindingDocumentation, getReferenceDoc, evaluateBudgetsForRun,
+                         
 } from './mcp-tools.js';
 import { listRuns } from './list-runs.js';
                                                          
+                                                       
 import { MAX_NORMALIZE_PATTERN_LENGTH, MAX_NORMALIZE_PATTERNS } from './stage-alignment.js';
 
 const sourceSchema = z.union([
@@ -42,7 +44,7 @@ function toolErrorResult(error                                    )
   };
 }
 
-// diagnoseRun/compareRuns may carry a `markdown` field (only when the caller asked for
+// compareRuns may carry a `markdown` field (only when the caller asked for
 // format: 'md'); it never belongs in structuredContent (whose shape must stay stable regardless of
 // format), so it's stripped here and, when present, becomes content[0].text instead of JSON.stringify.
 function toolResultWithMarkdown                  (promise                                    )                          {
@@ -55,16 +57,40 @@ function toolResultWithMarkdown                  (promise
   );
 }
 
+// diagnose_run's own mapping: with `format: 'md'` the Markdown is the content and structuredContent
+// shrinks to a few headline fields, so a client that stores it does not store the whole report.
+function diagnoseToolResult(promise                            )                          {
+  return promise.then(
+    (value) => {
+      const { markdown, ...structuredContent } = value;
+      return markdown !== undefined
+        ? toCallToolResult(markdown, diagnoseHeadline(value))
+        : toCallToolResult(JSON.stringify(structuredContent), structuredContent                           );
+    },
+    toolErrorResult,
+  );
+}
+
 // Counterpart for the tools that never produce a markdown field: its own mapping, so there's no
 // need to cast T to pretend it might carry a `markdown` field it never does.
 function toolResult                  (promise            )                          {
   return promise.then((value) => toCallToolResult(JSON.stringify(value), value                           ), toolErrorResult);
 }
 
+// The handshake version of a server built without a `generator`: no package to read a version from.
+const UNKNOWN_VERSION = '0.0.0';
+
+// Shared by every tool that returns a run handle.
+const RUN_ID_NOTE = 'runId is a handle for the run this server process has cached. It differs per tool by design (compare_runs returns runIdA and runIdB, evaluate_budgets the runId of its first run) and per server process, so match runs by app.id and app.attemptId, not by runId.';
+
 /** `thresholds`: the bin's --thresholds overrides, applied to every analyzing tool for the life
- * of the server. Omitted, every tool runs the specification defaults. */
-export function createMcpServer({ thresholds }                                      = {})            {
-  const server = new McpServer({ name: 'sparkforensics', version: '1.0.0' });
+ * of the server. Omitted, every tool runs the specification defaults.
+ * `generator`: the host package's name, version and core build id. The server reports its version
+ * in the MCP handshake and every diagnose_run and compare_runs result carries the block. */
+export function createMcpServer(
+  { thresholds, generator }                                                                   = {},
+)            {
+  const server = new McpServer({ name: 'sparkforensics', version: generator?.version ?? UNKNOWN_VERSION });
 
   server.registerTool('list_runs', {
     description: 'List candidate Spark event-log runs from a local directory or a Spark History Server, before diagnosing one with the other tools.',
@@ -72,16 +98,22 @@ export function createMcpServer({ thresholds }
   }, (params) => toolResult(listRuns(params)));
 
   server.registerTool('diagnose_run', {
-    description: 'Diagnose a Spark run: the dashboard verdict (title, summary, and the top places to look, ranked by potential savings), thresholded findings with remediation text, an impact-ranked fix recommendation rollup, clean-check status, the checks the log lacked the data to run, and the writeTargets, metrics and effectiveConf blocks of the CLI report. When the server was started with --thresholds, findings and clean checks from a tuned detector carry tunedThresholds, and their impact estimates are uncalibrated.',
+    description: 'Diagnose a Spark run: the dashboard verdict (title, summary, and the top places to look, ranked by potential savings, each with its lead finding), findings, an impact-ranked fix recommendation rollup, and the writeTargets, metrics and effectiveConf blocks of the CLI report. view "compact" (the default) lists one short row per finding and leaves out the clean-check and not-checked lists; view "full" returns every finding with its remediation text and evidence, and those lists. Every finding row has a key that stays the same for the same finding in a rerun of the job (compare_runs rows list the same keys), and an id for get_finding_evidence. With format "md" the content is Markdown and structuredContent holds a few headline fields. When the server was started with --thresholds, findings and clean checks from a tuned detector carry tunedThresholds, and their impact estimates are uncalibrated. The result names the Spark application (app) and the build that wrote it (generator). ' + RUN_ID_NOTE,
     inputSchema: {
       ...runRefSchema, redact: z.boolean().optional(),
+      view: z.enum(['compact', 'full']).optional()
+        .describe('compact (default): one short row per finding. full: the CLI report\'s rows, clean checks and not-checked checks.'),
       include: z.array(z.enum(['summary', 'evidenceAvailability', 'detectors'])).optional(),
       impactBand: z.array(z.string()).optional(), type: z.array(z.string()).optional(), stageId: z.number().int().optional(),
+      minBand: z.enum(['critical', 'warning', 'info']).optional()
+        .describe('List only findings at this band or a more severe one.'),
+      maxFindings: z.number().int().nonnegative().optional()
+        .describe('List at most this many findings, most severe first. findingsOmitted counts the ones left out; each verdict step still carries its lead finding.'),
       ...formatSchema,
     },
-  }, ({ source, runId, redact, include, format, impactBand, type, stageId }) => toolResultWithMarkdown(
+  }, ({ source, runId, redact, include, format, impactBand, type, stageId, view, minBand, maxFindings }) => diagnoseToolResult(
     resolveOrCreateRun({ source, runId }).then(({ runId: id }) =>
-      diagnoseRun(id, { redact, include, markdown: format === 'md', impactBand, type, stageId, thresholds })),
+      diagnoseRun(id, { redact, include, markdown: format === 'md', impactBand, type, stageId, thresholds, generator, view: view ?? 'compact', minBand, maxFindings })),
   ));
 
   server.registerTool('get_run_summary', {
@@ -92,7 +124,7 @@ export function createMcpServer({ thresholds }
   ));
 
   server.registerTool('compare_runs', {
-    description: 'Compare two runs: the verdict, metric deltas (metrics), categorized findings delta (findings) and the stage pairs (stagePairs) with the share of executor run time they cover (runtimeCoverage). confidence is ok, low or insufficient. metricDeltas and findingsDelta repeat metrics and findings under their earlier names and will be removed.',
+    description: 'Compare two runs: the verdict, metric deltas (metrics), categorized findings delta (findings), the stage pairs (stagePairs) with the share of executor run time they cover (runtimeCoverage), and comparability: the configuration differences, plan equality, data volume, executor capacity and the factors that bridge the wall-clock difference. confidence is ok, low or insufficient. metricDeltas and findingsDelta repeat metrics and findings under their earlier names and will be removed. The result names both Spark applications (baselineApp, candidateApp) and the build that wrote it (generator). Each findings row lists its stage names in stages and the same names without call-site directories in stageLabels. ' + RUN_ID_NOTE,
     inputSchema: {
       runIdA: z.string().optional(), sourceA: sourceSchema.optional(),
       ...secondRunRefSchema,
@@ -101,14 +133,18 @@ export function createMcpServer({ thresholds }
         .describe('Extra blocks to return. stagePairs: one row per paired stage with its deltas, which can be large.'),
       normalizePath: z.array(z.string().max(MAX_NORMALIZE_PATTERN_LENGTH)).max(MAX_NORMALIZE_PATTERNS).optional()
         .describe('Regular expressions whose every match in a plan node\'s text is replaced with a fixed token before stages are paired, so run-specific text (an output directory that differs per run) does not keep the same stage from pairing. A generic pattern, not only for paths. Affects stage pairing, runtimeCoverage and confidence, never findings. A pattern that backtracks catastrophically can stall the server: keep them simple and anchored.'),
+      ignoreConf: z.array(z.string().max(MAX_NORMALIZE_PATTERN_LENGTH)).max(MAX_NORMALIZE_PATTERNS).optional()
+        .describe('Regular expressions matched against Spark configuration keys. A key that matches is left out of comparability.conf, for keys that differ by design such as a per-run output path. Per-run identity keys (application id, start time, driver address) are always left out.'),
+      noiseBand: z.number().min(0).max(1).optional()
+        .describe('Share of the baseline value under which a metric row is marked withinNoise (default 0.02). Never changes a row\'s direction.'),
       ...formatSchema,
     },
-  }, ({ runIdA, sourceA, runIdB, sourceB, redact, include, normalizePath, format }) => toolResultWithMarkdown(
-    compareRuns({ runId: runIdA, source: sourceA }, { runId: runIdB, source: sourceB }, { redact, markdown: format === 'md', thresholds, normalizePath, include }),
+  }, ({ runIdA, sourceA, runIdB, sourceB, redact, include, normalizePath, ignoreConf, noiseBand, format }) => toolResultWithMarkdown(
+    compareRuns({ runId: runIdA, source: sourceA }, { runId: runIdB, source: sourceB }, { redact, markdown: format === 'md', thresholds, normalizePath, ignoreConf, noiseBand, include, generator }),
   ));
 
   server.registerTool('evaluate_budgets', {
-    description: 'Evaluate a run against pass/fail thresholds, optionally against a baseline run for regression budgets. With two runs, absolute budgets apply to the candidate (sourceB/runIdB), matching the CLI. A run with no ApplicationEnd always adds an inconclusive run-complete result.',
+    description: 'Evaluate a run against pass/fail thresholds, optionally against a baseline run for regression budgets. With two runs, absolute budgets apply to the candidate (sourceB/runIdB), matching the CLI. A run with no ApplicationEnd always adds an inconclusive run-complete result. ' + RUN_ID_NOTE,
     inputSchema: {
       source: sourceSchema.optional().describe('The run to evaluate. When sourceB/runIdB is given, this is the regression baseline instead, and the absolute budgets apply to sourceB/runIdB.'),
       runId: runRefSchema.runId.describe('Same as `source`, referencing an already-resolved run by id.'),