sparkforensics-server 0.5.1 → 0.6.0

package/vendor-core/stage-alignment.js

@@ -3,16 +3,20 @@
 // pairs. `compareRuns` calls it, and every surface that compares runs reads its result
 // (`stagePairs`) instead of comparing stage keys.
 //
-// Pairing keys on `comparisonIdentity`: the `stageIdentity` recipe run with the comparison
-// normalizer, so the volatile tokens that make two runs of one job differ (staging directories,
-// dates, IN-lists, Delta log file counts) and the caller's `--normalize-path`
-// patterns do not split a stage in two. `stageIdentity` itself stays the frozen exact key.
+// Pairing runs in two levels (see `alignStages`). The exact key is `comparisonIdentity`: the
+// `stageIdentity` recipe run with the comparison normalizer, so the volatile tokens that make two
+// runs of one job differ (staging directories, dates, IN-lists, Delta log file counts) and the
+// caller's `--normalize-path` patterns do not split a stage in two. A coarser structural key
+// (`stage-structure.ts`) and a detail similarity pair what the exact key splits. `stageIdentity`
+// itself stays the frozen exact key.
 
 import { normalizeDetail } from './detectors.js';
 import { isDeltaLogRead, scanRelationId } from './plan-summary.js';
 import { withEarlierAttempts, totalExecutorCpuMs } from './run-totals.js';
 import { planNodesOfStage } from './stage-plan-nodes.js';
-import { identityIndexWith, pairEqualCounts, stageIdentityWith,                       } from './stage-identity.js';
+import { normalizeStageName, stageIdentityWith,                       } from './stage-identity.js';
+import { alignSequences } from './sequence-alignment.js';
+import { attributeNames, detailTokens, jaccard, structuralKey } from './stage-structure.js';
                                                              
                                                   
 
@@ -136,29 +140,83 @@ export const PAIR_DELTA_METRICS = [
                  
                          
                          
+                                                                                                    
+                                                                                                
+                                       
                                               
-                                  
+                                                                                          
+                                                             
                 
                                               
  
+
+/** The stages an aligned execution pair left unpaired when its two sides ran different numbers of
+ * stages: a different plan (a broadcast join in place of an exchange and a sort-merge join), not
+ * changed work. `deltas` totals each metric over the leftover stages of each side. */
+                                 
+                          
+                          
+                         
+                         
+                                              
+ 
+
+                                     
+                                                                                      
+                         
+                         
+                                                  
+                           
+                                                                                       
+                   
+                                                                                                    
+                                                                                                 
+                                                                              
+                           
+                                                                                                      
+                                          
+                    
+ 
 
                                  
                      
-                                                                       
+                                                                                                     
                                                                 
-                                                                                  
-                     
+                                                                                    
+                              
                                                                                               
                                                                           
-                                                                                                
-                                     
+                                                                          
+                                                                                                      
+                           
                                  
+                                         
  
 
                                
                                                                
                                     
  
+
+/** An execution pair scores at least this (0-1) on call site, description and plan structure to be
+ * matched. */
+export const EXECUTION_MATCH_MIN = 0.55;
+/** Share of the smaller run's executions that must pair (see `ExecutionAlignment.agreement`) for the two runs
+ * to count as one job. Below it no stage pairs: stages as generic as a `count` or a `collect` repeat
+ * across unrelated jobs, and only the surrounding executions tell the jobs apart. */
+export const MIN_EXECUTION_AGREEMENT = 0.5;
+/** Detail similarity (Jaccard over a stage's name and normalized node text) two stages of different
+ * structure need to pair as `aligned`. */
+export const ALIGNED_MIN_SIMILARITY = 0.6;
+/** Score of a pair made by position alone: no plan evidence backs it. */
+export const POSITIONAL_SCORE = 0.5;
+/** Execution similarities cached at most (distinct signatures in one run times those in the other). */
+const MAX_CACHED_SIMILARITIES = 1_000_000;
+/** Leftover stage pairs scored in one execution pair; above it the `aligned` pass is skipped. */
+const MAX_STAGE_SIMILARITY_CELLS = 250_000;
+/** Whether replanned run time counts in the numerator of `runtimeCoverage` (and so toward the `ok`
+ * gate). When false it counts in the denominator only. */
+export const REPLANNED_COUNTS_TOWARD_COVERAGE = true;
 
 // Sum of a field over the stage's own record and the work its figures leave out (earlier
 // attempts, a failed attempt's late tasks), the same all-attempt sums the run totals use.
@@ -172,7 +230,9 @@ function attemptSum(rows         , field
   return present ? sum : null;
 }
 
-function stageFigures(stage       )                                         {
+                                                      
+
+function stageFigures(stage       )          {
   const rows = withEarlierAttempts([stage]);
   return {
     executorRunTime: attemptSum(rows, 'executorRunTime'),
@@ -186,77 +246,341 @@ function stageFigures(stage       )                                         {
   };
 }
 
+function deltasOf(b         , c         )                                      {
+  const deltas = {}                                       ;
+  for (const metric of PAIR_DELTA_METRICS) {
+    const [bv, cv] = [b[metric], c[metric]];
+    deltas[metric] = { baseline: bv, candidate: cv, delta: bv != null && cv != null ? cv - bv : null };
+  }
+  return deltas;
+}
+
+/** Each metric summed over several stages' figures; null where no stage recorded it. */
+function sumFigures(rows           )          {
+  const total = {}           ;
+  for (const metric of PAIR_DELTA_METRICS) {
+    let sum = 0, present = false;
+    for (const row of rows) if (row[metric] != null) { sum += row[metric] ; present = true; }
+    total[metric] = present ? sum : null;
+  }
+  return total;
+}
+
 const ascending = (a        , b        )         => a - b;
 
-/** Pairs the stages of two runs. At this stage the pairing is `matchStages`' algorithm over
- * `comparisonIdentity`: stages sharing an identity pair off by sorted id when each run has the same
- * count of them, and every pair is `exact`. */
+// ---- Per-run index --------------------------------------------------------------------------
+
+// What the aligner knows about one SQL execution (or the pseudo-execution of stages outside any):
+// the non-bookkeeping stages it ran and the three things its similarity reads.
+                    
+                                       
+                    
+                   
+                     
+                                                                                                 
+                                                    
+                                                                                                          
+                        
+                                                                 
+                     
+                            
+                          
+                                                                                                 
+                    
+ 
+
+                    
+                        
+                                   
+                           
+                                
+                                            
+                         
+                          
+ 
+
+// Stack frames of the JVM and Spark themselves say nothing about which user code ran.
+const FRAMEWORK_FRAME = /^(java|javax|jdk|sun|scala|py4j|org\.apache|io\.delta|io\.netty|com\.sun)\b/;
+
+function userFrames(details                    )           {
+  const frames           = [];
+  for (const line of (details ?? '').split('\n')) {
+    const frame = line.trim().replace(/:\d+\)$/, ')'); // a shifted line number is not a different call site
+    if (frame && !FRAMEWORK_FRAME.test(frame)) frames.push(frame);
+  }
+  return frames;
+}
+
+// Directory prefixes carry the run's own paths (a container directory, an application id), so only
+// each path's last segment stays in a description.
+const descriptionTokens = (text        , normalizer                  )           =>
+  [...new Set(normalizer(text).replace(/\S*\/([^/\s]+)/g, '$1').split(/[^A-Za-z0-9_.$]+/).filter(Boolean))].sort();
+
+// An execution's plan structure: its operator names (a repeated operator counts as often as it
+// repeats) and the attribute names its nodes mention, which tell two plans of the same operators
+// apart. Neither carries a literal, a path or an id.
+function planStructure(root          )           {
+  const tokens           = [];
+  const attributes = new Set        ();
+  (function walk(node          )       {
+    if (!/^(WholeStageCodegen|InputAdapter|ColumnarToRow)\b/.test(node.name ?? '')) {
+      tokens.push(normalizeStageName(node.name ?? ''));
+      for (const name of attributeNames(node.detail ?? '')) attributes.add(`@${name}`);
+    }
+    for (const child of node.children ?? []) walk(child);
+  })(root);
+  return [...tokens, ...attributes].sort();
+}
+
+function indexRun(
+  snap                 , normalizer                  , signatures                     , interned                     ,
+)           {
+  const intern = (tokens          )             => {
+    const ids = new Int32Array(tokens.length);
+    tokens.forEach((t, i) => {
+      let id = interned.get(t);
+      if (id === undefined) { id = interned.size; interned.set(t, id); }
+      ids[i] = id;
+    });
+    return ids.sort();
+  };
+  const nodesOf = new Map                    ();
+  const bookkeeping = new Set        ();
+  const exactKey = new Map                ();
+  const structuralKeyOf = new Map                       ();
+  const byExecution = new Map                         ();
+  for (const [id, stage] of snap.stages) {
+    const nodes = planNodesOfStage(stage, snap.sql);
+    nodesOf.set(id, nodes);
+    if (isDeltaBookkeepingStage(stage, snap.sql, nodes)) { bookkeeping.add(id); continue; }
+    exactKey.set(id, comparisonIdentity(stage, snap, normalizer, nodes));
+    structuralKeyOf.set(id, structuralKey(nodes));
+    const execId = stage.sqlExecutionId ?? null;
+    const ids = byExecution.get(execId);
+    if (ids) ids.push(id); else byExecution.set(execId, [id]);
+  }
+  const info = (execId               , stageIds          )           => {
+    stageIds.sort(ascending);
+    const root = execId === null ? null : snap.sql.get(execId)?.planTree ?? null;
+    const structure = root ? planStructure(root)
+      : stageIds.map((id) => structuralKeyOf.get(id) ?? `n:${normalizeStageName(snap.stages.get(id) .name ?? '')}`).sort();
+    const frames = [...new Set(stageIds.flatMap((id) => userFrames(snap.stages.get(id) .details)))].sort();
+    const description = execId === null ? [] : descriptionTokens(snap.sql.get(execId)?.description ?? '', normalizer);
+    const text = JSON.stringify([structure, frames, description]);
+    let signature = signatures.get(text);
+    if (signature === undefined) { signature = signatures.size; signatures.set(text, signature); }
+    return { id: execId, stageIds, structure: intern(structure), frames: intern(frames), description: intern(description), signature };
+  };
+  const executions = [...byExecution.keys()].filter((k)              => k !== null).sort(ascending)
+    .map((execId) => info(execId, byExecution.get(execId) ));
+  const pseudoIds = byExecution.get(null);
+  return {
+    snap, nodesOf, bookkeeping, exactKey, structuralKey: structuralKeyOf, executions,
+    pseudo: pseudoIds ? info(null, pseudoIds) : null,
+  };
+}
+
+// Weights of the three parts of an execution pair's similarity. A part one side lacks (a PySpark
+// stack trace has no user frames, a description may be empty) drops out of the mean.
+const STRUCTURE_WEIGHT = 4, FRAMES_WEIGHT = 2, DESCRIPTION_WEIGHT = 1;
+
+/** 0-1000 (rounded, so the alignment compares integers). */
+function executionSimilarity(a          , b          )         {
+  let sum = STRUCTURE_WEIGHT * jaccard(a.structure, b.structure), weight = STRUCTURE_WEIGHT;
+  if (a.frames.length > 0 && b.frames.length > 0) { sum += FRAMES_WEIGHT * jaccard(a.frames, b.frames); weight += FRAMES_WEIGHT; }
+  if (a.description.length > 0 && b.description.length > 0) {
+    sum += DESCRIPTION_WEIGHT * jaccard(a.description, b.description);
+    weight += DESCRIPTION_WEIGHT;
+  }
+  return Math.round((1000 * sum) / weight);
+}
+
+// ---- Stage alignment inside one execution pair -----------------------------------------------
+
+                                                                                                  
+
+function alignWithin(
+  base          , cand          , be          , ce          ,
+  tokens                                                              , normalizer                  ,
+)                                                               {
+  const pseudo = be.id === null;
+  const freeBase = new Set(be.stageIds), freeCand = new Set(ce.stageIds);
+  const pairs            = [];
+  const take = (baseId        , candId        , quality                    , score        ) => {
+    pairs.push({ baseId, candId, quality, score });
+    freeBase.delete(baseId);
+    freeCand.delete(candId);
+  };
+  const tokensOf = (run          , cache                       , id        )           => {
+    let t = cache.get(id);
+    if (!t) { const stage = run.snap.stages.get(id) ; t = detailTokens(stage.name, run.nodesOf.get(id) , normalizer); cache.set(id, t); }
+    return t;
+  };
+  const similarity = (baseId        , candId        )         =>
+    jaccard(tokensOf(base, tokens.base, baseId), tokensOf(cand, tokens.cand, candId));
+  const group = (free             , keyOf                               )                        => {
+    const groups = new Map                  ();
+    for (const id of [...free].sort(ascending)) {
+      const key = keyOf(id);
+      if (key === null) continue;
+      const ids = groups.get(key);
+      if (ids) ids.push(id); else groups.set(key, [id]);
+    }
+    return groups;
+  };
+  // Stages sharing a key pair off in id order, as many as both sides have: a self-join's subtree
+  // counted three times in one run and twice in the other still pairs two.
+  const pairByKey = (
+    keyOfBase                               , keyOfCand                               ,
+    quality                    , scoreOf                                            ,
+  ) => {
+    const b = group(freeBase, keyOfBase), c = group(freeCand, keyOfCand);
+    for (const key of [...b.keys()].sort()) {
+      const candIds = c.get(key);
+      if (!candIds) continue;
+      const baseIds = b.get(key) ;
+      for (let i = 0; i < Math.min(baseIds.length, candIds.length); i++) take(baseIds[i], candIds[i], quality, scoreOf(baseIds[i], candIds[i]));
+    }
+  };
+
+  // Stages outside any SQL execution have no plan: the stage's own call-site text tells them apart.
+  const detailsKey = (run          , id        ) => normalizeStageName(normalizer(run.snap.stages.get(id) .details ?? ''));
+  pairByKey(
+    (id) => base.exactKey.get(id)  + (pseudo ? `§${detailsKey(base, id)}` : ''),
+    (id) => cand.exactKey.get(id)  + (pseudo ? `§${detailsKey(cand, id)}` : ''),
+    'exact', () => 1,
+  );
+  pairByKey((id) => base.structuralKey.get(id) ?? null, (id) => cand.structuralKey.get(id) ?? null, 'structural', similarity);
+
+  // Different structure, similar details: best score first, ties by lower ids.
+  const withStructure = (run          , free             ) => [...free].filter((id) => run.structuralKey.get(id) != null).sort(ascending);
+  const leftBase = withStructure(base, freeBase), leftCand = withStructure(cand, freeCand);
+  if (leftBase.length * leftCand.length <= MAX_STAGE_SIMILARITY_CELLS) {
+    const candidates                                                           = [];
+    for (const baseId of leftBase) for (const candId of leftCand) {
+      const score = similarity(baseId, candId);
+      if (score >= ALIGNED_MIN_SIMILARITY) candidates.push({ baseId, candId, score });
+    }
+    candidates.sort((x, y) => y.score - x.score || x.baseId + x.candId - (y.baseId + y.candId) || x.baseId - y.baseId);
+    for (const { baseId, candId, score } of candidates) {
+      if (freeBase.has(baseId) && freeCand.has(candId)) take(baseId, candId, 'aligned', score);
+    }
+  }
+
+  // No plan structure to compare: pair by position among the stages of the same name.
+  const byName = (run          ) => (id        ) =>
+    run.structuralKey.get(id) == null ? normalizeStageName(run.snap.stages.get(id) .name ?? '') : null;
+  pairByKey(byName(base), byName(cand), 'aligned', () => POSITIONAL_SCORE);
+
+  return { pairs, leftBase: [...freeBase].sort(ascending), leftCand: [...freeCand].sort(ascending) };
+}
+
+/** Pairs the stages of two runs in two levels. SQL executions align first, in submission order, by an
+ * order-preserving sequence alignment scored on call site, description and plan structure (the
+ * stages outside any execution form one pseudo-execution per run); then the stages of each aligned
+ * execution pair align: equal comparison key (`exact`), equal structural key (`structural`), similar
+ * details (`aligned`), or position among plan-less stages of one name (`aligned`). Stages an
+ * execution pair with different stage counts leaves over are `replanned`; with equal counts they
+ * stay `unmatched`. Deterministic, and swapping the runs mirrors the pairs. */
 export function alignStages(baseSnap                 , candSnap                 , options               = {})                 {
   const normalizer = comparisonDetailNormalizer(options.normalizePath);
-  // One walk of the plan per stage serves the bookkeeping test and the identity.
-  const index = (snap                 ) => {
-    const nodesOf = new Map                    ();
-    const bookkeeping = new Set        ();
-    for (const [id, stage] of snap.stages) {
-      const nodes = planNodesOfStage(stage, snap.sql);
-      nodesOf.set(id, nodes);
-      if (isDeltaBookkeepingStage(stage, snap.sql, nodes)) bookkeeping.add(id);
-    }
-    const identities = identityIndexWith(
-      snap, (stage, id) => comparisonIdentity(stage, snap, normalizer, nodesOf.get(id)), (id) => !bookkeeping.has(id),
-    );
-    return { identities, bookkeeping };
+  const signatures = new Map                ();
+  const interned = new Map                ();
+  const base = indexRun(baseSnap, normalizer, signatures, interned), cand = indexRun(candSnap, normalizer, signatures, interned);
+
+  // Execution similarity is cached per signature pair, so a loop of identical queries scores once.
+  // When the runs hold so many distinct signatures that the cache could not repay its memory, it is off.
+  const distinct = (run          ) => new Set(run.executions.map((e) => e.signature)).size;
+  const cached = distinct(base) * distinct(cand) <= MAX_CACHED_SIMILARITIES;
+  const cache = new Map                ();
+  const similarityOf = (a          , b          )         => {
+    if (a.signature === b.signature) return 1000;
+    if (!cached) return executionSimilarity(a, b);
+    const key = a.signature * signatures.size + b.signature;
+    let s = cache.get(key);
+    if (s === undefined) { s = executionSimilarity(a, b); cache.set(key, s); }
+    return s;
   };
-  const base = index(baseSnap), cand = index(candSnap);
-  const baseBook = base.bookkeeping, candBook = cand.bookkeeping;
-  const { pairs: idPairs } = pairEqualCounts(base.identities, cand.identities);
+  const sequence = alignSequences(
+    base.executions.length, cand.executions.length,
+    (i, j) => similarityOf(base.executions[i], cand.executions[j]), Math.round(1000 * EXECUTION_MATCH_MIN),
+    (i) => base.executions[i].id , (j) => cand.executions[j].id ,
+  );
+  const smaller = Math.min(base.executions.length, cand.executions.length);
+  const agreement = smaller > 0 ? sequence.pairs.length / smaller : null;
+  const accepted = agreement === null || agreement >= MIN_EXECUTION_AGREEMENT;
+
+  const executionPairs                              = [];
+  if (accepted) {
+    for (const [i, j] of sequence.pairs) executionPairs.push([base.executions[i], cand.executions[j]]);
+    if (base.pseudo && cand.pseudo) executionPairs.push([base.pseudo, cand.pseudo]);
+  }
 
-  const baseFigures = new Map                                                ();
-  const candFigures = new Map                                                ();
-  const figures = (cache                    , snap                 , id        ) => {
+  const baseFigures = new Map                 (), candFigures = new Map                 ();
+  const figures = (cache                      , snap                 , id        )          => {
     let f = cache.get(id);
     if (!f) { f = stageFigures(snap.stages.get(id) ); cache.set(id, f); }
     return f;
   };
+  const figuresOf = (side                 , ids          )            =>
+    ids.map((id) => side === 'base' ? figures(baseFigures, baseSnap, id) : figures(candFigures, candSnap, id));
 
-  const pairs              = idPairs
-    .map(({ baseId, candId })            => {
-      const b = figures(baseFigures, baseSnap, baseId), c = figures(candFigures, candSnap, candId);
-      const deltas = {}                                       ;
-      for (const metric of PAIR_DELTA_METRICS) {
-        const [bv, cv] = [b[metric], c[metric]];
-        deltas[metric] = { baseline: bv, candidate: cv, delta: bv != null && cv != null ? cv - bv : null };
-      }
-      return { pairId: `b${baseId}-c${candId}`, baseStageIds: [baseId], candStageIds: [candId], quality: 'exact', score: 1, deltas };
-    })
-    .sort((x, y) => x.baseStageIds[0] - y.baseStageIds[0] || x.candStageIds[0] - y.candStageIds[0]);
+  const tokens = { base: new Map                  (), cand: new Map                  () };
+  const pairs              = [];
+  const replanned                   = [];
+  for (const [be, ce] of executionPairs) {
+    const result = alignWithin(base, cand, be, ce, tokens, normalizer);
+    for (const { baseId, candId, quality, score } of result.pairs) {
+      pairs.push({
+        pairId: `b${baseId}-c${candId}`, baseStageIds: [baseId], candStageIds: [candId], quality, score,
+        deltas: deltasOf(figures(baseFigures, baseSnap, baseId), figures(candFigures, candSnap, candId)),
+      });
+    }
+    // Different stage counts under one aligned execution: the plan changed, not the work. The
+    // pseudo-execution has no plan to re-plan, so its leftovers stay unmatched.
+    const leftover = result.leftBase.length + result.leftCand.length > 0;
+    if (leftover && be.id !== null && ce.id !== null && be.stageIds.length !== ce.stageIds.length) {
+      replanned.push({
+        baseExecutionId: be.id, candExecutionId: ce.id, baseStageIds: result.leftBase, candStageIds: result.leftCand,
+        deltas: deltasOf(sumFigures(figuresOf('base', result.leftBase)), sumFigures(figuresOf('cand', result.leftCand))),
+      });
+    }
+  }
+  pairs.sort((x, y) => x.baseStageIds[0] - y.baseStageIds[0] || x.candStageIds[0] - y.candStageIds[0]);
+  replanned.sort((x, y) => x.baseExecutionId - y.baseExecutionId || x.candExecutionId - y.candExecutionId);
 
   const pairedBase = new Set(pairs.flatMap((p) => p.baseStageIds));
   const pairedCand = new Set(pairs.flatMap((p) => p.candStageIds));
-  const unmatchedOf = (snap                 , book             , paired             )           =>
-    [...snap.stages.keys()].filter((id) => !book.has(id) && !paired.has(id)).sort(ascending);
+  const replannedBase = new Set(replanned.flatMap((g) => g.baseStageIds));
+  const replannedCand = new Set(replanned.flatMap((g) => g.candStageIds));
+  const unmatchedOf = (snap                 , book             , paired             , replannedIds             )           =>
+    [...snap.stages.keys()].filter((id) => !book.has(id) && !paired.has(id) && !replannedIds.has(id)).sort(ascending);
 
   // Run time counts every attempt, the same figure the stage-pair deltas and the run totals use.
-  const runTime = (cache                    , snap                 , id        )         => figures(cache, snap, id).executorRunTime ?? 0;
   let total = 0, matched = 0;
-  for (const id of baseSnap.stages.keys()) {
-    if (baseBook.has(id)) continue;
-    const t = runTime(baseFigures, baseSnap, id);
-    total += t;
-    if (pairedBase.has(id)) matched += t;
-  }
-  for (const id of candSnap.stages.keys()) {
-    if (candBook.has(id)) continue;
-    const t = runTime(candFigures, candSnap, id);
-    total += t;
-    if (pairedCand.has(id)) matched += t;
-  }
+  const tally = (cache                      , snap                 , book             , paired             , replannedIds             ) => {
+    for (const id of snap.stages.keys()) {
+      if (book.has(id)) continue;
+      const t = figures(cache, snap, id).executorRunTime ?? 0;
+      total += t;
+      if (paired.has(id) || (REPLANNED_COUNTS_TOWARD_COVERAGE && replannedIds.has(id))) matched += t;
+    }
+  };
+  tally(baseFigures, baseSnap, base.bookkeeping, pairedBase, replannedBase);
+  tally(candFigures, candSnap, cand.bookkeeping, pairedCand, replannedCand);
 
   return {
     pairs,
-    unmatched: { baseStageIds: unmatchedOf(baseSnap, baseBook, pairedBase), candStageIds: unmatchedOf(candSnap, candBook, pairedCand) },
-    replanned: [],
-    bookkeepingStageIds: { baseStageIds: [...baseBook].sort(ascending), candStageIds: [...candBook].sort(ascending) },
+    unmatched: {
+      baseStageIds: unmatchedOf(baseSnap, base.bookkeeping, pairedBase, replannedBase),
+      candStageIds: unmatchedOf(candSnap, cand.bookkeeping, pairedCand, replannedCand),
+    },
+    replanned,
+    bookkeepingStageIds: { baseStageIds: [...base.bookkeeping].sort(ascending), candStageIds: [...cand.bookkeeping].sort(ascending) },
     runtimeCoverage: total > 0 ? matched / total : null,
+    executionAlignment: {
+      baseExecutions: base.executions.length, candExecutions: cand.executions.length,
+      pairedExecutions: sequence.pairs.length, bounded: sequence.bounded, agreement, accepted,
+    },
   };
 }

package/vendor-core/stage-quantiles.js

@@ -1,4 +1,5 @@
                                                             
+import { medianOfSorted } from './median.js';
                                                                              
 
 // Single source of truth for the packed per-task numeric array: FIELDS (offset
@@ -304,6 +305,7 @@ function listScheduleEndMs(
   return endMs;
 }
 
+// p50 is the textbook median (the mean of the two middle values on an even count); p95 is nearest-rank.
 export function computeFieldQuantiles(arr              , fieldIndex        )                                            {
   const taskCount = arr.length / FIELDS.STRIDE;
   if (taskCount === 0) return { p50: 0, p95: 0, max: 0 };
@@ -313,7 +315,7 @@ export function computeFieldQuantiles(arr              , fieldIndex        )
   values.sort();
 
   return {
-    p50: values[Math.ceil(taskCount * 0.50) - 1],
+    p50: medianOfSorted(values),
     p95: values[Math.ceil(taskCount * 0.95) - 1],
     max: values[taskCount - 1],
   };

package/vendor-core/stage-structure.js

@@ -0,0 +1,83 @@
+// What the stage aligner compares beyond the exact comparison key: a stage's structural key (operator
+// tree shape, node names and sorted attribute names, with literals, paths, file counts and ids
+// removed) and the token sets its similarity scores read. Pure.
+
+import { cyrb53 } from './string-hash.js';
+import { normalizeStageName,                       } from './stage-identity.js';
+                                           
+
+// Plumbing nodes: codegen boundaries and input adapters change with how Spark fuses a stage, not with
+// the query, so the structural key and the similarity tokens skip them.
+const PLUMBING_NODE = /^(WholeStageCodegen|InputAdapter|ColumnarToRow|RowToColumnar)\b/;
+
+const isPlumbing = (node          )          => PLUMBING_NODE.test(node.name ?? '');
+
+/** The attribute names a plan node's text mentions (`amount#12` gives `amount`), without ids, each
+ * once, sorted. Sorting makes the key insensitive to the nondeterministic order in which Spark lists
+ * grouping and projection columns; reading only `name#id` references leaves literals out. */
+export function attributeNames(detail        )           {
+  const names = new Set        ();
+  for (const m of detail.matchAll(/([A-Za-z_][\w$.]*)#\d+L?/g)) names.add(m[1]);
+  return [...names].sort();
+}
+
+/** The structural key of a stage from the plan nodes attributed to it, or null when nothing but
+ * plumbing is attributed. The nodes form a forest (a node's parent is its nearest attributed
+ * ancestor); the key folds each node's normalized name, its sorted attribute names and its
+ * children's digests (sorted, so a join's side order does not matter). Only structure goes in: no
+ * node detail, so a literal, a path or a file count never splits two stages. */
+export function structuralKey(nodes                     )                {
+  const attributed = new Set(nodes.filter((n) => !isPlumbing(n)));
+  if (attributed.size === 0) return null;
+  const digests = new Map                  ();
+  const nested = new Set          ();
+  // Digests of the nearest attributed descendants of `node`'s children.
+  const below = (node          )           => {
+    const out           = [];
+    for (const child of node.children ?? []) {
+      if (attributed.has(child)) { out.push(digestOf(child)); nested.add(child); }
+      else out.push(...below(child));
+    }
+    return out;
+  };
+  const digestOf = (node          )         => {
+    let d = digests.get(node);
+    if (d === undefined) {
+      d = cyrb53(JSON.stringify([normalizeStageName(node.name ?? ''), attributeNames(node.detail ?? ''), below(node).sort()]));
+      digests.set(node, d);
+    }
+    return d;
+  };
+  for (const node of attributed) digestOf(node);
+  const roots = [...attributed].filter((n) => !nested.has(n)).map(digestOf).sort();
+  return cyrb53(JSON.stringify(roots));
+}
+
+const TOKEN_SPLIT = /[^A-Za-z0-9_.$]+/;
+
+/** Sorted distinct tokens of a stage's attributed nodes (name and normalized detail) and its name.
+ * Two stages whose text differs in one literal share nearly every token. */
+export function detailTokens(stageName                    , nodes                     , normalize                  )           {
+  const tokens = new Set        ();
+  const add = (text        ) => { for (const t of text.split(TOKEN_SPLIT)) if (t) tokens.add(t); };
+  add(normalizeStageName(stageName ?? ''));
+  for (const node of nodes) {
+    if (isPlumbing(node)) continue;
+    add(normalizeStageName(node.name ?? ''));
+    add(normalize(node.detail ?? ''));
+  }
+  return [...tokens].sort();
+}
+
+/** Jaccard similarity of two sorted arrays; 1 when both are empty. An element repeated in both counts
+ * as often as it repeats in the shorter side (multiset Jaccard), so distinct arrays give the plain one. */
+export function jaccard(a                            , b                            )         {
+  if (a.length === 0 && b.length === 0) return 1;
+  let i = 0, j = 0, both = 0;
+  while (i < a.length && j < b.length) {
+    if (a[i] === b[j]) { both++; i++; j++; }
+    else if (a[i] < b[j]) i++;
+    else j++;
+  }
+  return both / (a.length + b.length - both);
+}

package/vendor-core/types.js

@@ -338,9 +338,19 @@
                                                                                                  
                                                                                                
                                                                                    
-                                                                                                                                  
-                                                                     
+                                                                                                  
+                                                                                             
+                                                                                                 
+                                                                                                  
+                        
                                                     
+                                                                                                 
+                                                                                                  
+                                                                                                
+                                                                                                    
+                                                                                                  
+                                                                                        
+                                                 
  
 
 // `Finding` is a union discriminated on `type`, one member per emitted finding type: see