sparkforensics-server 0.5.1 → 0.5.2

package/public/index.html

@@ -23,14 +23,14 @@
           document.documentElement.setAttribute('data-theme', 'light');
       } catch (_) {}
     </script>
-    <script type="module" crossorigin src="./assets/index-DCeWge12.js"></script>
+    <script type="module" crossorigin src="./assets/index-B-03mG7K.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-BYl-AzN5.js">
     <link rel="modulepreload" crossorigin href="./assets/react-vendor-DEdfrRTJ.js">
-    <link rel="modulepreload" crossorigin href="./assets/DisclosureContext-B0siMVdg.js">
+    <link rel="modulepreload" crossorigin href="./assets/DisclosureContext-ZpE6CkHx.js">
     <link rel="stylesheet" crossorigin href="./assets/plan-graph-vendor-DLioOiRN.css">
-    <link rel="stylesheet" crossorigin href="./assets/index-BcqTLKFp.css">
+    <link rel="stylesheet" crossorigin href="./assets/index-2h_TgUAb.css">
   </head>
   <body>
     <div id="root"></div>

package/vendor-core/cli/budgets.js

@@ -3,6 +3,7 @@ import { computeSkewRatio, ENTRY_BY_TYPE,                         } from '../det
 import { effectiveThresholds } from '../threshold-overrides.js';
 import { IMPACT_BAND_ORDER } from '../format-utils.js';
                                                               
+import { PAIR_DELTA_METRICS,                                      } from '../stage-alignment.js';
                                                                  
                                                                 
 
@@ -14,13 +15,23 @@ const IMPACT_BANDS = Object.keys(IMPACT_BAND_ORDER)                ;
                                                                                   
                                                                                                  
                                          
+                                                                                                                        
+                                              
+                                                                                                            
+                                                                                   
+                                          
  
+
+export const STAGE_QUALITIES                                  = ['exact', 'structural', 'aligned'];
+export const DEFAULT_STAGE_BUDGET_QUALITIES                                  = ['exact', 'structural'];
+/** Metrics with a regression direction (higher is worse). Input and output volume are workload, not performance. */
+export const NEUTRAL_PAIR_METRICS                      = new Set(['inputBytes', 'outputBytes']);
                                
                                                                                             
-                                                               
+                                                                                        
                                                 
                  
-                                                                            
+                                                                                                       
                   
  
 
@@ -146,6 +157,50 @@ function checkRegression(comparison                   , maxRegressionPct
     : { name: 'max-regression', metric: regressionMetric, status: 'pass', detail: `Metric "${regressionMetric}" ${pctLabel}, within budget ${maxRegressionPct}%.` };
 }
 
+function checkStageRegression(
+  comparison                   , { metric, maxPct }                  , qualities                                 ,
+)               {
+  const name = 'max-stage-regression'         ;
+  if (!(PAIR_DELTA_METRICS                     ).includes(metric)) {
+    return { name, metric, status: 'inconclusive', detail: `Metric "${metric}" is not a paired-stage metric (expected one of: ${PAIR_DELTA_METRICS.join(', ')}).` };
+  }
+  if (NEUTRAL_PAIR_METRICS.has(metric)) {
+    return { name, metric, status: 'inconclusive', detail: `Metric "${metric}" measures workload volume, not performance: it has no regression direction to check.` };
+  }
+  const eligible = comparison.stagePairs.filter((p) => qualities.includes(p.quality));
+  if (eligible.length === 0) {
+    return { name, metric, status: 'inconclusive', detail: comparison.stagePairs.length === 0
+      ? 'No stages were paired between the two runs.'
+      : `None of the ${comparison.stagePairs.length} paired stage(s) has quality ${qualities.join(' or ')}.` };
+  }
+  const measured = eligible
+    .map((pair) => ({ pair, delta: pair.deltas[metric                   ] }))
+    .filter(({ delta }) => delta.baseline != null && delta.delta != null);
+  if (measured.length === 0) {
+    return { name, metric, status: 'inconclusive', detail: `Metric "${metric}" is unavailable for every eligible paired stage.` };
+  }
+  const regressions = measured
+    .filter(({ delta }) => delta.delta  > 0)
+    .map(({ pair, delta }) => ({ pair, delta, pct: delta.baseline === 0 ? Infinity : (delta.delta  / delta.baseline ) * 100 }))
+    .sort((a, b) => b.pct - a.pct || a.pair.pairId.localeCompare(b.pair.pairId));
+  const over = regressions.filter((r) => r.pct > maxPct);
+  const scope = `${measured.length} paired stage(s)`;
+  if (over.length === 0) {
+    const worst = regressions[0];
+    return { name, metric, status: 'pass', detail: worst
+      ? `No paired stage regressed "${metric}" beyond ${maxPct}% across ${scope}; the largest was ${formatPct(worst.pct)} (pair ${worst.pair.pairId}).`
+      : `No paired stage regressed "${metric}" across ${scope}.` };
+  }
+  const listed = over.slice(0, 3).map((r) => `pair ${r.pair.pairId} (${r.pair.quality}) ${formatPct(r.pct)}`).join(', ');
+  const more = over.length > 3 ? `, and ${over.length - 3} more` : '';
+  return { name, metric, status: 'violation',
+    detail: `${over.length} of ${scope} regressed "${metric}" beyond ${maxPct}%: ${listed}${more}.` };
+}
+
+function formatPct(pct        )         {
+  return pct === Infinity ? 'from 0' : `+${pct.toFixed(1)}%`;
+}
+
 function checkFailOnIntroduced(comparison                   , band        )               {
   if (band !== 'all' && !IMPACT_BANDS.includes(band              )) {
     return { name: 'fail-on-introduced', status: 'inconclusive', detail: `Impact band "${band}" is not recognized (expected "all" or one of ${IMPACT_BANDS.join(', ')}).` };
@@ -198,6 +253,11 @@ export function evaluateBudgets({ appModel, catalog, budgets, comparison, thresh
   for (const { metric, maxPct } of budgets.regressionBudgets ?? []) {
     pushComparisonBudget(results, comparison, 'max-regression', (c) => checkRegression(c, maxPct, metric), metric);
   }
+  const stageQualities = budgets.stageQualities ?? DEFAULT_STAGE_BUDGET_QUALITIES;
+  for (const budget of budgets.stageRegressionBudgets ?? []) {
+    pushComparisonBudget(results, comparison, 'max-stage-regression',
+      (c) => checkStageRegression(c, budget, stageQualities), budget.metric);
+  }
   if (budgets.failOnIntroduced !== undefined) {
     pushComparisonBudget(results, comparison, 'fail-on-introduced',
       (c) => checkFailOnIntroduced(c, budgets.failOnIntroduced ));

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

@@ -4,6 +4,9 @@
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { COMPARISON_METRIC_KEYS } from '../run-comparison.js';
+import { PAIR_DELTA_METRICS } from '../stage-alignment.js';
+import { NEUTRAL_PAIR_METRICS, STAGE_QUALITIES } from './budgets.js';
+                                                       
 
                                                                      
                                                                                      
@@ -81,3 +84,35 @@ export function combineRegressionBudgets(sources                          )
   }
   return sources.map((s) => s.budget);
 }
+
+/** Refuses a stage budget metric that is not a paired-stage metric or has no regression direction. */
+export function assertStageBudgetMetric(metric        , origin        )       {
+  if (!(PAIR_DELTA_METRICS                     ).includes(metric)) {
+    throw new Error(`${origin}: unknown paired-stage metric "${metric}" (expected one of: ${PAIR_DELTA_METRICS.filter((m) => !NEUTRAL_PAIR_METRICS.has(m)).join(', ')}).`);
+  }
+  if (NEUTRAL_PAIR_METRICS.has(metric)) {
+    throw new Error(`${origin}: "${metric}" measures workload volume, not performance, so it has no regression direction to budget.`);
+  }
+}
+
+/** One `--stage-regression-budget` value, `<metric>:<pct>`, over the paired-stage metrics. */
+export function parseStageRegressionBudgetFlag(spec        )                   {
+  const origin = `--stage-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);
+  assertStageBudgetMetric(metric, origin);
+  if (!PCT_PATTERN.test(pct)) throw new Error(`${origin}: "${pct}" is not a non-negative percentage.`);
+  return { metric, maxPct: Number(pct) };
+}
+
+/** The pair qualities a stage budget reads, from a comma list such as `exact,structural`. */
+export function parseStageQualities(list        , origin        )                         {
+  const qualities = list.split(',').map((q) => q.trim()).filter(Boolean);
+  const bad = qualities.find((q) => !(STAGE_QUALITIES                     ).includes(q));
+  if (qualities.length === 0 || bad !== undefined) {
+    throw new Error(`${origin}: ${bad === undefined ? 'no quality given' : `unknown quality "${bad}"`} (expected a list from: ${STAGE_QUALITIES.join(', ')}).`);
+  }
+  return qualities                          ;
+}

package/vendor-core/comparison-output.js

@@ -11,7 +11,7 @@ import { redactComparison } from './redact.js';
                                                                  
                            
                                                                                             
-                                                                                    
+                                                                                                           
                                                    
 
 /** `full` carries every field (the CLI); `summary` leaves out `stagePairs` (MCP, which returns them
@@ -33,6 +33,7 @@ export function comparisonOutput(comparison                   , view
     unmatched: comparison.unmatched,
     replanned: comparison.replanned,
     bookkeepingStageIds: comparison.bookkeepingStageIds,
+    executionAlignment: comparison.executionAlignment,
   };
 }
 

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

@@ -1 +1 @@
-6e0ac29f74ae092b14c5700dfa86d3273fce7d1af59005c6e2e450a91da92d5e
+7aaca3af812e0e5a4f4632ad7577fc438b589520a27422ce8c986b156de82260