sparkforensics-server 0.5.0 → 0.5.2

package/vendor-core/mcp-tools.js

@@ -6,13 +6,14 @@ import { collectRun } from './cli/collect-run.js';
 import { deriveEvidenceAvailability } from './evidence-availability.js';
 import { resolveFromShs, DEFAULT_MAX_ARCHIVE_BYTES, DEFAULT_IDLE_TIMEOUT_MS } from './shs-load.js';
 import { mcpError } from './mcp-error.js';
-import { buildEvidenceReport, toFindingsFilter,                                                                                                               } from './evidence-report.js';
-import { redactComparison } from './redact.js';
+import { buildEvidenceReport, runFindings, toFindingsFilter,                                                                                                               } from './evidence-report.js';
 import { computeWallClock } from './wall-clock.js';
-import { analyze } from './analyzer.js';
-import { buildComparison, renderComparisonMarkdown,                        } from './run-comparison.js';
-import { comparisonVerdict,                            } from './comparison-verdict.js';
+import { renderComparisonMarkdown,                        } from './run-comparison.js';
+import { buildComparisonOutput,                       } from './comparison-output.js';
+import { compileNormalizePatterns } from './stage-alignment.js';
+import { runOutputBlocks } from './run-output.js';
 import { evaluateBudgets,                                       } from './cli/budgets.js';
+import { assertStageBudgetMetric, combineRegressionBudgets } from './cli/regression-budgets.js';
 import { FINDING_NAMES, titleCase } from './finding-names.js';
 import { docAnchorForType } from './detector-docs.js';
 import { DETECTORS,                         } from './detectors.js';
@@ -46,19 +47,15 @@ import { typeTag } from './format-utils.js';
                                                                                                
                      
  
-// compareRuns returns a smaller MCP-facing projection of CompareRunsResult
-// (runIdA/runIdB/verdict/findingsDelta/metricDeltas/confidence/reason/matchedCoverage), not the full
-// raw shape (no baselineLabel/stageSkew/baseStages/candStages/jobOutcomes).
-                                       
+// compareRuns returns the shared comparison projection (comparison-output.ts, the CLI's `comparison`
+// object), not the full raw shape (no baselineLabel/stageSkew/baseStages/candStages/jobOutcomes).
+// `verdict` is the dashboard comparison page's headline (baseline = runIdA, candidate = runIdB).
+                                                                
                  
                  
-                                                                                      
-                                 
-                                               
-                                             
+                                                                               
                                               
-                                      
-                                                        
+                                            
  
 
 function envInt(name        , fallback        )         {
@@ -192,6 +189,7 @@ export function diagnoseRun(runId        , opts
                                                                                                       
                                                                                                          
                                                     
+                                                                                 
                                                                                                                 {
   const appModel = getCachedAppModel(runId);
   const findingsFilter = toFindingsFilter(opts?.impactBand, opts?.type, opts?.stageId);
@@ -203,6 +201,9 @@ export function diagnoseRun(runId        , opts
   return {
     runId, verdict: json.verdict, findings: json.findings, recommendations: json.recommendations, cleanChecks: json.cleanChecks,
     notRunChecks: json.notRunChecks,
+    // The CLI report's own blocks, so a run reads the same through either surface.
+    writeTargets: json.writeTargets,
+    ...runOutputBlocks(appModel, { redact: opts?.redact, thresholds: opts?.thresholds }),
     runComplete: appModel.app?.endTime != null,
     // Top level too, so a client that never asks for `summary` still sees the run was tuned.
     ...(tuned ? { tunedThresholds: tuned } : {}),
@@ -345,16 +346,19 @@ async function resolveAndAnalyze(
   ref        , thresholds                                ,
 )                                                                     {
   const { runId, appModel } = await resolveOrCreateRun(ref);
-  const catalog = analyze(
-    appModel.app, appModel.stages, appModel.executors.added, appModel.executors.removed,
-    appModel.jobs, appModel.sql, appModel.runAggregates, { thresholds },
-  );
-  return { runId, appModel, catalog };
+  return { runId, appModel, catalog: runFindings(appModel, thresholds).catalog };
 }
 
 export async function compareRuns(
-  a        , b        , opts                                                                            ,
+  a        , b        , opts                                                                                                              
+                                                                                                                  ,
 )                                                                                                           {
+  // Before any log is read: a bad pattern refuses the call, as the CLI's usage error does.
+  try {
+    compileNormalizePatterns(opts?.normalizePath);
+  } catch (e) {
+    throw mcpError('access-or-upstream-failure', `normalizePath: ${(e         ).message}`);
+  }
   const [
     { runId: runIdA, appModel: appModelA, catalog: catalogA },
     { runId: runIdB, appModel: appModelB, catalog: catalogB },
@@ -364,26 +368,20 @@ export async function compareRuns(
   // interactive stage-detail drill-down, which none of compare/matchStages/metricDeltas/findingsDelta
   // read. Findings/metrics come from `catalog` and appModel.stages/sql, both fully populated. Produces
   // identical output to the dashboard; the MCP tool just never exposes per-task drill-down.
-  const built = buildComparison(
+  const { comparison, output } = buildComparisonOutput(
     { label: runIdA, appModel: appModelA, catalog: catalogA },
     { label: runIdB, appModel: appModelB, catalog: catalogB },
+    { redact: opts?.redact, normalizePath: opts?.normalizePath, view: opts?.include?.includes('stagePairs') ? 'full' : 'summary' },
   );
-  // Stage names throughout `built` carry raw Spark stage text, which can embed a host/IP token as
-  // free text, the same residual redactReport() already scrubs from the evidence report.
-  const result = opts?.redact ? redactComparison(built) : built;
-  const verdict = comparisonVerdict(result);
 
   return {
     runIdA,
     runIdB,
-    verdict,
-    findingsDelta: result.findings,
-    metricDeltas: result.metrics,
-    confidence: result.confidence,
-    reason: result.reason,
-    matchedCoverage: result.matchedCoverage,
+    ...output,
+    findingsDelta: output.findings,
+    metricDeltas: output.metrics,
     ...tunedField(opts?.thresholds),
-    ...(opts?.markdown ? { markdown: renderComparisonMarkdown(result, verdict, tunedDetectors(opts?.thresholds)) } : {}),
+    ...(opts?.markdown ? { markdown: renderComparisonMarkdown(comparison, output.verdict, tunedDetectors(opts?.thresholds)) } : {}),
   };
 }
 
@@ -408,6 +406,25 @@ export async function evaluateBudgetsForRun(
   if (budgets.regressionMetric !== undefined && budgets.maxRegressionPct === undefined) {
     throw mcpError('access-or-upstream-failure', 'regressionMetric requires maxRegressionPct.');
   }
+  // The CLI's rule: a metric is budgeted once across the single pair and the list.
+  try {
+    const pair = budgets.maxRegressionPct === undefined ? [] : [{ metric: budgets.regressionMetric ?? 'wallClock', maxPct: budgets.maxRegressionPct }];
+    combineRegressionBudgets([
+      ...pair.map((budget) => ({ origin: 'maxRegressionPct/regressionMetric', budget })),
+      ...(budgets.regressionBudgets ?? []).map((budget) => ({ origin: 'regressionBudgets', budget })),
+    ]);
+  } catch (e) {
+    throw mcpError('access-or-upstream-failure', (e         ).message);
+  }
+  if (budgets.stageQualities !== undefined && budgets.stageRegressionBudgets === undefined) {
+    throw mcpError('access-or-upstream-failure', 'stageQualities requires stageRegressionBudgets.');
+  }
+  try {
+    for (const { metric } of budgets.stageRegressionBudgets ?? []) assertStageBudgetMetric(metric, 'stageRegressionBudgets');
+    combineRegressionBudgets((budgets.stageRegressionBudgets ?? []).map((budget) => ({ origin: 'stageRegressionBudgets', budget })));
+  } catch (e) {
+    throw mcpError('access-or-upstream-failure', (e         ).message);
+  }
   const [first, second] = await Promise.all([
     resolveAndAnalyze(primary, opts?.thresholds),
     secondary ? resolveAndAnalyze(secondary, opts?.thresholds) : Promise.resolve(undefined),
@@ -418,11 +435,12 @@ export async function evaluateBudgetsForRun(
   // apply to the candidate.
   const candidate = second ?? first;
   const baseline = second ? first : undefined;
+  // Not redacted: no budget reads the stage text redaction rewrites (the parity suite checks it).
   const comparison                                = baseline
-    ? buildComparison(
+    ? buildComparisonOutput(
       { label: baseline.runId, appModel: baseline.appModel, catalog: baseline.catalog },
       { label: candidate.runId, appModel: candidate.appModel, catalog: candidate.catalog },
-    )
+    ).comparison
     : undefined;
 
   const { results, violated, inconclusive } = evaluateBudgets({

package/vendor-core/median.js

@@ -0,0 +1,8 @@
+// The textbook median of values already sorted ascending: the middle value for an odd count, the
+// mean of the two middle values for an even one. 0 for an empty list.
+export function medianOfSorted(sorted                   )         {
+  const n = sorted.length;
+  if (n === 0) return 0;
+  const mid = n >> 1;
+  return n % 2 === 1 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}

package/vendor-core/plan-graph-model.js

@@ -1,6 +1,6 @@
 // Flattens a resolved planTree into a { nodes, edges } graph shape for the
 // React Flow + Dagre plan graph view ("Plan graph view" in
-// docs-site/contributor-guide/architecture/drill-down.md). The Exchange
+// docs-site/contributor-guide/architecture/drill-down/plan-graph.md). The Exchange
 // write/read split is done upstream now, in resolvePlanTree
 // (event-handlers.ts): this file just walks the already-split tree and maps
 // each real PlanNode onto a PlanGraphNodeData. sourceNodeId still lets a

package/vendor-core/plan-summary.js

@@ -44,6 +44,17 @@ function pushLongFilterWarning(result             , len        )       {
   result.warnings.push({ type: 'longFilterCondition', detail: `Filter condition is ${len} characters: consider simplifying or pushing the filter down closer to the scan.` });
 }
 
+// True when a node reads internal Delta metadata: the _delta_log state scan or an anonymous
+// commit/checkpoint read. `Location:` is often truncated to `Del...`, so it also keys off
+// DeltaLogFileIndex or the Delta-log action column signature. (Column-signature heuristic: a
+// future Spark renaming those action columns would leak a noise row; acceptable.) Shared by
+// `scanRelationId` and the comparison's Delta bookkeeping flag (stage-alignment.ts).
+export function isDeltaLogRead(name        , detail        )          {
+  return /_delta_log/.test(name) || /_delta_log/.test(detail) ||
+    /DeltaLogFileIndex/i.test(name + detail) ||
+    /checkpointMetadata#|sidecar#|commitInfo#/.test(name + detail);
+}
+
 // Stable relation-identity key for a scan node: "<format>:<relation>" (e.g.
 // "delta:mx.store_map", "parquet:warehouse.sales", "jdbc:dw.dim_product")
 // or null when the node is internal Delta metadata / a non-scan / un-nameable.
@@ -70,16 +81,8 @@ export function scanRelationId(name        , detail        )                {
     return `${format}:${table.replace(/^spark_catalog\./, '')}`;
   }
 
-  // 2. Internal Delta metadata (the _delta_log state scan and anonymous
-  //    commit/checkpoint reads) → null. Location: is often truncated to `Del...`,
-  //    so also key off DeltaLogFileIndex or the Delta-log action column signature.
-  //    (Column-signature heuristic: a future Spark renaming those action columns
-  //    would leak a noise row; acceptable.)
-  if (/_delta_log/.test(name) || /_delta_log/.test(detail) ||
-      /DeltaLogFileIndex/i.test(name + detail) ||
-      /checkpointMetadata#|sidecar#|commitInfo#/.test(name + detail)) {
-    return null;
-  }
+  // 2. Internal Delta metadata (see isDeltaLogRead) → null.
+  if (isDeltaLogRead(name, detail)) return null;
 
   // 3. Anonymous real file read (InMemoryFileIndex, no catalog name) →
   //    best-effort Location basename. Preserves temp/snapshot self-reuse; a

package/vendor-core/run-comparison.js

@@ -1,12 +1,12 @@
 import { computeWallClock } from './wall-clock.js';
 import { normalizeDetail } from './detectors.js';
-import { cyrb53 } from './string-hash.js';
+import { normalizeStageName, stageIdentityWith, identityIndexWith, pairEqualCounts } from './stage-identity.js';
 import { computeAllocation } from './allocation.js';
 import { totalExecutorCpuMs, withEarlierAttempts } from './run-totals.js';
-import { planNodesOfStage } from './stage-plan-nodes.js';
 import { captureSnapshot } from './session-snapshot.js';
+import { alignStages, compileNormalizePatterns, COMPARISON_SCHEMA_VERSION,                                     } from './stage-alignment.js';
 import { tunedRunNote } from './threshold-overrides.js';
-                                                                                                    
+                                                                                          
                                                              
                                                                                         
 import { isIncompleteRun } from './check-coverage.js';
@@ -21,13 +21,27 @@ import { summarizeRunOutcome } from './run-outcome.js';
                                    
                                                                                                                         
  
+                               
+                                                               
+                                                                          
+ 
                                     
                                                 
-                                                  
+                                                                                                
+                                                                   
+                                                                                                 
+                                                                         
                           
+                                                            
+                                 
+                          
+                                         
+                                         
+                                                             
+                                                           
                             
                                                                              
-                                                                                                                                                  
+                            
                                                                             
                                                                             
                                                                                             
@@ -41,68 +55,10 @@ function jobOutcome(snapshot                 )                    {
   return { failedJobs, totalJobs, incomplete: isIncompleteRun(snapshot.catalog) };
 }
 
-// Replace run-varying tokens (digit runs, long hex ids) with a stable marker so
-// the same logical stage across two runs normalizes to one identity.
-export function normalizeStageName(name        )         {
-  return String(name)
-    .toLowerCase()
-    .replace(/\b[0-9a-f]{8,}\b/g, '#') // hex ids/uuids first (they contain digits)
-    .replace(/\d+/g, '#')
-    .replace(/\s+/g, ' ')
-    .trim();
-}
-
-// Bottom-up, order-independent structural identity of a resolved plan tree:
-// each node folds its normalized name/detail with its children's digests
-// (children sorted, so AQE picking a different broadcast side still matches),
-// so two plans collide only when their whole shape and every node's detail
-// agree. `normalizeDetail` strips the run-to-run noise (expr ids, `plan_id=`,
-// codegen numbers, AQE build-side choice, commutative-operand order). Each
-// node folds to a fixed-length cyrb53 digest (JSON.stringify-encoded, so
-// detail text containing `<`/`>`/`{`/`,` can't collide two different plans)
-// instead of embedding full child identity strings, which would re-escape
-// every level below and blow identity size up to ~2^depth on the 20-60+
-// operator-deep plans real Spark produces.
-function planTreeIdentity(root                             )                {
-  if (!root) return null;
-  function visit(node          )         {
-    const childDigests = (node.children ?? []).map(visit).sort();
-    return cyrb53(JSON.stringify([normalizeStageName(node.name ?? ''), normalizeDetail(node.detail ?? ''), childDigests]));
-  }
-  return visit(root);
-}
-
-// Plan identity for the stage's SQL execution, scoped to only the plan nodes
-// this stage actually ran (`node.stageIds`), not the whole tree: two stages
-// sharing one SQL execution (e.g. a self-join's two Exchange stages) otherwise
-// collapse onto one identity regardless of which part of the plan each ran.
-// Falls back to the coarser whole-tree identity when the stage has no
-// attributed nodes (hand-built snapshots without `stageIds`, or unmatched
-// accumulables).
-function sqlNodeIdentity(stage       , snapshot                              )         {
-  const execId = stage.sqlExecutionId;
-  if (execId == null) return '';
-  const root = snapshot.sql.get(execId)?.planTree ?? null;
-  if (!root) return '';
-  const fingerprints = planNodesOfStage(stage, snapshot.sql)
-    .map((node) => JSON.stringify([normalizeStageName(node.name ?? ''), normalizeDetail(node.detail ?? '')]));
-  if (fingerprints.length === 0) return planTreeIdentity(root) ?? '';
-  return cyrb53(JSON.stringify(fingerprints.sort()));
-}
+export { normalizeStageName };
 
 export function stageIdentity(stage       , snapshot                              )         {
-  return normalizeStageName(stage.name ?? '') + '§' + sqlNodeIdentity(stage, snapshot);
-}
-
-function identityIndex(snapshot                 )                        {
-  const byIdentity = new Map                  ();
-  for (const [id, stage] of snapshot.stages) {
-    const key = stageIdentity(stage, snapshot);
-    const ids = byIdentity.get(key);
-    if (ids) ids.push(id);
-    else byIdentity.set(key, [id]);
-  }
-  return byIdentity;
+  return stageIdentityWith(stage, snapshot, normalizeDetail);
 }
 
 export function matchStages(baseSnap                 , candSnap                 )   
@@ -111,10 +67,8 @@ export function matchStages(baseSnap                 , candSnap
                                    
                    
   {
-  const baseIdx = identityIndex(baseSnap);
-  const candIdx = identityIndex(candSnap);
-  const pairs                                                              = [];
-  const matchedIdentities = new Set        ();
+  const baseIdx = identityIndexWith(baseSnap, (stage) => stageIdentity(stage, baseSnap));
+  const candIdx = identityIndexWith(candSnap, (stage) => stageIdentity(stage, candSnap));
   const collisionIdentities = new Set        ();
   // A collision is a single-run property: more than one stage in the SAME run
   // shares an identity. Recorded per-run regardless of whether the other run
@@ -122,26 +76,7 @@ export function matchStages(baseSnap                 , candSnap
   // don't, so this set means "was ambiguous", not "stayed unpaired".
   for (const idx of [baseIdx, candIdx])
     for (const [identity, ids] of idx) if (ids.length > 1) collisionIdentities.add(identity);
-  // An identity colliding equally on both sides has no genuine ambiguity about
-  // *count*, so pair its stages off positionally by sorted id rather than
-  // dropping them. This is exact when the identity actually distinguishes
-  // stages (e.g. self-comparing a run: every stage matches itself). It's a
-  // best-effort guess when the identity is coarse (no SQL/attribution) and
-  // the two sides are genuinely different runs -- two unrelated same-named
-  // stages could get cross-paired. Accepted tradeoff: dropping them instead
-  // would also sacrifice the exact-self-comparison case, which matters more.
-  for (const identity of [...baseIdx.keys()].sort()) {
-    const candIds = candIdx.get(identity);
-    if (!candIds) continue;
-    const baseIds = baseIdx.get(identity) ;
-    if (baseIds.length !== candIds.length) continue;
-    const sortedBaseIds = [...baseIds].sort((a, b) => a - b);
-    const sortedCandIds = [...candIds].sort((a, b) => a - b);
-    for (let i = 0; i < sortedBaseIds.length; i++) {
-      pairs.push({ identity, baseId: sortedBaseIds[i], candId: sortedCandIds[i] });
-    }
-    matchedIdentities.add(identity);
-  }
+  const { pairs, matchedIdentities } = pairEqualCounts(baseIdx, candIdx);
   const total = baseSnap.stages.size + candSnap.stages.size;
   // Both runs stage-less: nothing to compare, not "nothing matched".
   const coverage = total === 0 ? 1 : (2 * pairs.length) / total;
@@ -348,19 +283,19 @@ function namesConflict(a                     , b                     )
 }
 
 // A pair's skew ratio is null when the stage's duration wasn't measurable (see
-// `stageSkewRatio`). `baseId`/`candId` are carried through so a consumer can
-// key rows uniquely: two pairs can share one `identity` (a same-run collision
-// resolved positionally in matchStages), but never the same baseId+candId.
-function stageSkewDeltas(
-  baseSnap                 ,
-  candSnap                 ,
-  match                                                                        ,
-)                                                                                                                                       {
-  return match.pairs.map((p) => {
-    const b = stageSkewRatio(baseSnap.stages.get(p.baseId) );
-    const c = stageSkewRatio(candSnap.stages.get(p.candId) );
-    return { identity: p.identity, baseId: p.baseId, candId: p.candId, baseline: b, candidate: c, delta: b != null && c != null ? c - b : null };
-  }).sort((x, y) => x.identity < y.identity ? -1 : x.identity > y.identity ? 1 : 0);
+// `stageSkewRatio`). Rows come from the aligner's `stagePairs`, so the table and the coverage
+// banner agree. A pair covers one stage per side here; `pairId` is the unique row key.
+function stageSkewDeltas(baseSnap                 , candSnap                 , stagePairs             )                 {
+  return stagePairs.map((p) => {
+    const baseId = p.baseStageIds[0], candId = p.candStageIds[0];
+    const baseStage = baseSnap.stages.get(baseId) ;
+    const b = stageSkewRatio(baseStage);
+    const c = stageSkewRatio(candSnap.stages.get(candId) );
+    return {
+      pairId: p.pairId, name: normalizeStageName(baseStage.name ?? ''), baseId, candId,
+      baseline: b, candidate: c, delta: b != null && c != null ? c - b : null,
+    };
+  }).sort((x, y) => x.name < y.name ? -1 : x.name > y.name ? 1 : x.baseId - y.baseId);
 }
 
 // Compact, view-friendly per-stage record for the manual stage-pinning panel.
@@ -402,6 +337,14 @@ function stageList(snap                 )
 // caller's reference, so one shared empty Map is safe here.
 const EMPTY_TASK_DATA = new Map                 ();
 
+                                 
+                                                                                                  
+                                                                                               
+                                                                                                   
+                                                                                             
+                                    
+ 
+
 // Wraps the analyze()-to-compareRuns() snapshot-building sequence shared by
 // the CLI's --baseline path and mcp-tools.ts's compareRuns tool: both need
 // captureSnapshot (with an empty taskDataCache, the interactive drill-down
@@ -410,50 +353,66 @@ const EMPTY_TASK_DATA = new Map                 ();
 export function buildComparison(
   baseline                                                           ,
   candidate                                                           ,
+  options                 ,
 )                    {
   return compareRuns(
     { label: baseline.label, snapshot: captureSnapshot(baseline.appModel, baseline.catalog, EMPTY_TASK_DATA) },
     { label: candidate.label, snapshot: captureSnapshot(candidate.appModel, candidate.catalog, EMPTY_TASK_DATA) },
+    options,
   );
 }
 
-// matchStages' coverage is a Dice coefficient: (2 * pairs.length) / (baseCount
-// + candCount). Below 0.5, more than half of each run's stages went unpaired,
-// so the stage-level rows (stageSkew, baseStages/candStages) mostly show
-// unrelated work side by side rather than the same stage before/after -- the
-// comparison is dominated by guesswork, not genuine pairing. 0.5 is thus the
-// natural midpoint for "more matched than not," not an arbitrary tuning knob.
-const LOW_COVERAGE_THRESHOLD = 0.5;
+// `ok` needs this share of both runs' executor run time to sit in paired stages. Run time, not
+// stage count: the stages a run spends its time in decide whether a per-stage delta compares the
+// same work, and a count lets many small matched stages hide an unmatched heavy one.
+const RUNTIME_COVERAGE_THRESHOLD = 0.9;
 
 export function compareRuns(
   baseline                                              ,
   candidate                                              ,
+  options                 = {},
 )                    {
   const baseSnap = baseline.snapshot, candSnap = candidate.snapshot;
+  // The old exact matcher stays the source of `matchedCoverage`; pairs and the gate come from the aligner.
   const match = matchStages(baseSnap, candSnap);
+  const alignment = alignStages(baseSnap, candSnap, { normalizePath: compileNormalizePatterns(options.normalizePath) });
+  const runtimeCoverage = alignment.runtimeCoverage;
   // Name equality is a weak confidence signal, not a hard gate: renaming a job
   // is the normal way to label an A/B experiment, so a mismatch must not block
   // the (matching-free, name-independent) deltas. Surface it as `low` instead.
   const namesDiffer = namesConflict(baseSnap.app, candSnap.app);
-  // Coverage is the other half of the signal: identical names on two runs that
-  // barely share any stages are just as misleading as differing names on two
-  // runs that match well, so either condition alone drops confidence to `low`.
-  const lowCoverage = match.coverage < LOW_COVERAGE_THRESHOLD;
-  const reason = namesDiffer && lowCoverage
-    ? `Run names differ and only ${(match.coverage * 100).toFixed(0)}% of stages matched, so deltas may compare different work.`
+  // Runtime coverage is the other half of the signal: identical names on two runs whose heavy
+  // stages do not pair are just as misleading as differing names on two runs that pair well, so
+  // either condition alone drops confidence to `low`. No run time at all is `insufficient`.
+  const insufficient = runtimeCoverage === null;
+  const lowCoverage = runtimeCoverage !== null && runtimeCoverage < RUNTIME_COVERAGE_THRESHOLD;
+  const confidence                                  = insufficient ? 'insufficient' : namesDiffer || lowCoverage ? 'low' : 'ok';
+  // Rounded down, so a share just under the gate never reads as 90%.
+  const share = runtimeCoverage === null ? '' : `${Math.floor(runtimeCoverage * 100)}%`;
+  const reason = insufficient
+    ? `${namesDiffer ? 'Run names differ and no' : 'No'} executor run time was recorded in either run, so there is no work to compare.`
+    : namesDiffer && lowCoverage
+    ? `Run names differ and only ${share} of executor run time is in matched stages, so deltas may compare different work.`
     : namesDiffer
     ? 'Run names differ, so deltas may compare different work.'
     : lowCoverage
-    ? `Only ${(match.coverage * 100).toFixed(0)}% of stages matched between runs, so per-stage rows mostly compare unrelated work.`
+    ? `Only ${share} of executor run time is in matched stages, so per-stage rows mostly compare unrelated work.`
     : null;
   return {
     baselineLabel: baseline.label, candidateLabel: candidate.label,
-    confidence: namesDiffer || lowCoverage ? 'low' : 'ok',
+    confidence,
     reason,
     matchedCoverage: match.coverage,
+    comparisonSchemaVersion: COMPARISON_SCHEMA_VERSION,
+    runtimeCoverage,
+    stagePairs: alignment.pairs,
+    unmatched: alignment.unmatched,
+    replanned: alignment.replanned,
+    bookkeepingStageIds: alignment.bookkeepingStageIds,
+    executionAlignment: alignment.executionAlignment,
     metrics: metricDeltas(baseSnap, candSnap),
     findings: findingsDelta(baseSnap, candSnap),
-    stageSkew: stageSkewDeltas(baseSnap, candSnap, match),
+    stageSkew: stageSkewDeltas(baseSnap, candSnap, alignment.pairs),
     baseStages: stageList(baseSnap),
     candStages: stageList(candSnap),
     jobOutcomes: { baseline: jobOutcome(baseSnap), candidate: jobOutcome(candSnap) },
@@ -491,11 +450,13 @@ export function renderComparisonMarkdown(
     if (verdict.sentences.length > 0) lines.push('', verdict.sentences.join(' '));
     lines.push('');
   }
-  if (comparison.confidence === 'low') {
-    lines.push(`- confidence: low, ${comparison.reason}`);
+  if (comparison.confidence !== 'ok') {
+    lines.push(`- confidence: ${comparison.confidence}, ${comparison.reason}`);
     lines.push('');
   }
   lines.push(`- matched stage coverage: ${(comparison.matchedCoverage * 100).toFixed(1)}%`);
+  lines.push(`- runtime coverage: ${comparison.runtimeCoverage === null ? 'n/a' : `${(comparison.runtimeCoverage * 100).toFixed(1)}%`}`);
+  lines.push(`- stage pairs: ${comparison.stagePairs.length}, unmatched: ${comparison.unmatched.baseStageIds.length} baseline / ${comparison.unmatched.candStageIds.length} candidate, Delta bookkeeping: ${comparison.bookkeepingStageIds.baseStageIds.length} baseline / ${comparison.bookkeepingStageIds.candStageIds.length} candidate`);
   lines.push('');
   lines.push('### Metric deltas');
   lines.push('');

package/vendor-core/run-output.js

@@ -0,0 +1,26 @@
+import { runFindings } from './evidence-report.js';
+import { redactRunModel } from './redact.js';
+import { computeRunMetrics,                 } from './run-metrics.js';
+import { buildEffectiveConf,                    } from './effective-conf.js';
+                                                         
+                                           
+
+/** The CLI report's `metrics` and `effectiveConf` blocks, shared with MCP diagnose_run. Under
+ * `redact` they come from the run redacted with the report's own inputs, so host and app
+ * pseudonyms match the report's. `confKeys`/`confRedactRegex` narrow and mask `effectiveConf`. */
+export function runOutputBlocks(
+  appModel          ,
+  { redact, thresholds, confKeys, confRedactRegex }   
+                                                                                                     
+    = {},
+)                                                               {
+  let blocksModel = appModel;
+  if (redact) {
+    const { catalog, config } = runFindings(appModel, thresholds);
+    blocksModel = redactRunModel(appModel, catalog, config).appModel;
+  }
+  return {
+    metrics: computeRunMetrics(blocksModel, thresholds),
+    effectiveConf: buildEffectiveConf(blocksModel.app, { keys: confKeys, userPattern: confRedactRegex }),
+  };
+}

package/vendor-core/sequence-alignment.js

@@ -0,0 +1,83 @@
+// Order-preserving sequence alignment: the weighted longest-common-subsequence dynamic program the
+// stage aligner runs over each run's SQL executions. Pure and deterministic.
+//
+// Cost: the full table has n*m cells and one similarity call per cell. Above `FULL_ALIGNMENT_MAX_CELLS`
+// the table is restricted to a band around the diagonal, which costs about n*(2W+1) cells with
+// W = `BAND_BASE_HALF_WIDTH` + |n-m|/2, and the result reports that the bounded form ran.
+
+/** Largest n*m the alignment runs in full (1000 x 1000 executions). */
+export const FULL_ALIGNMENT_MAX_CELLS = 1_000_000;
+/** Band half-width added to half of |n-m| once the table is bounded: the band is centered on the line
+ * from corner to corner, and a run of insertions or deletions in one place drifts the best path from
+ * that line by at most |n-m|/2. */
+export const BAND_BASE_HALF_WIDTH = 100;
+
+                                    
+                                                        
+                                 
+                                                                          
+                   
+ 
+
+/** Aligns two sequences of lengths `n` and `m`, maximizing the summed `score` of matched pairs. `score`
+ * returns a non-negative integer; a pair scoring below `minScore` is never matched. Of equally good
+ * alignments the one that matches whenever matching is optimal wins, and where it must skip, it skips the
+ * element with the higher id (`idA`, `idB`), so the lower ids stay and swapping the two sequences mirrors
+ * the pairs. */
+export function alignSequences(
+  n        , m        ,
+  score                                  ,
+  minScore        ,
+  idA                       , idB                       ,
+)                    {
+  if (n === 0 || m === 0) return { pairs: [], bounded: false };
+  const bounded = n * m > FULL_ALIGNMENT_MAX_CELLS;
+  const half = BAND_BASE_HALF_WIDTH + Math.ceil(Math.abs(n - m) / 2);
+  // Row i may match columns lo[i]..hi[i]; both bounds only grow with i.
+  const lo = new Int32Array(n), hi = new Int32Array(n);
+  for (let i = 0; i < n; i++) {
+    const center = Math.floor((i * m) / n);
+    lo[i] = bounded ? Math.max(0, center - half) : 0;
+    hi[i] = bounded ? Math.min(m - 1, center + half) : m - 1;
+  }
+  // best[i][j - lo[i]]: the best total from the suffixes starting at (i, j), for j inside row i's band.
+  const best               = new Array(n);
+  // Cells outside the band are not stored: left of it the row's first cell stands in (those columns can
+  // only match in later rows, whose bands start no earlier), right of it the row cannot match, so the
+  // next row answers.
+  const get = (i        , j        )         => {
+    for (;;) {
+      if (i >= n || j >= m) return 0;
+      if (j < lo[i]) j = lo[i];
+      else if (j > hi[i]) i++;
+      else return best[i][j - lo[i]];
+    }
+  };
+  // The caller memoizes `score`, so the walk below re-asking for visited cells is cheap.
+  const cell = score;
+  for (let i = n - 1; i >= 0; i--) {
+    const row = new Int32Array(hi[i] - lo[i] + 1);
+    best[i] = row;
+    for (let j = hi[i]; j >= lo[i]; j--) {
+      let v = Math.max(get(i + 1, j), j + 1 <= hi[i] ? row[j + 1 - lo[i]] : get(i + 1, j + 1));
+      const s = cell(i, j);
+      if (s >= minScore) v = Math.max(v, s + get(i + 1, j + 1));
+      row[j - lo[i]] = v;
+    }
+  }
+
+  const pairs                          = [];
+  let i = 0, j = 0;
+  while (i < n && j < m) {
+    if (j < lo[i]) { j = lo[i]; continue; }
+    if (j > hi[i]) { i++; continue; }
+    const v = best[i][j - lo[i]];
+    const s = cell(i, j);
+    if (s >= minScore && s + get(i + 1, j + 1) === v) { pairs.push([i, j]); i++; j++; continue; }
+    const skipA = get(i + 1, j) === v, skipB = get(i, j + 1) === v;
+    if (skipA && skipB) { if (idA(i) >= idB(j)) i++; else j++; }
+    else if (skipA) i++;
+    else j++;
+  }
+  return { pairs, bounded };
+}