sparkforensics-server 0.5.1 → 0.5.2

package/vendor-core/evidence-report.js

@@ -180,29 +180,29 @@ export const EVIDENCE_SCHEMA_VERSION         = 5;
 // module (stageShape's totalCores, utilization's unrounded fraction) is left off both, so it never
 // reaches the report; adding, renaming or dropping a key here changes the report contract.
 const EVIDENCE_KEYS = {
-  skew: [],
+  skew: ['origin'],
   stageShape: ['rule'],
-  shuffle: [],
-  partitionSizing: ['rule'],
-  spill: ['spillMagnitude'],
+  shuffle: ['partitions'],
+  partitionSizing: ['rule', 'origin', 'partitions'],
+  spill: ['spillMagnitude', 'reads'],
   gc: ['direction'],
   slowHost: ['variant', 'host', 'hostTaskShare', 'hostMeanMs', 'dimension', 'executorId', 'execMaxValue'],
-  stageSlowness: [],
+  stageSlowness: ['reads'],
   stageFailed: ['variant', 'numTasks', 'memoryBytesSpilled', 'failedTaskDetails'],
   failures: ['failedTasks', 'dominantReason', 'dominantError', 'failureGroups', 'otherFailedTasks'],
-  straggler: ['unit', 'speculativeTasks', 'stragglerCount'],
+  straggler: ['unit', 'speculativeTasks', 'stragglerCount', 'origin'],
   speculationWaste: [],
   retryWaste: ['numTasks', 'memoryBytesSpilled', 'retriedTaskDetails'],
-  tinyTask: [],
+  tinyTask: ['reads'],
   incompleteRun: [],
-  coldStart: [],
+  coldStart: ['dynamicAllocation'],
   utilization: ['cpuUtilizationPct'],
   memoryUtilization: ['variant', 'rule', 'executorId', 'heap', 'dataUnavailable'],
   cacheUtilization: [
     'variant', 'rddId', 'rddName', 'memorySize', 'diskSize', 'numCachedPartitions', 'numPartitions', 'dataUnavailable',
   ],
   coreLocality: ['nonLocalTaskCount'],
-  autoscalingChurn: ['shortLivedExecutorCount'],
+  autoscalingChurn: ['shortLivedExecutorCount', 'dynamicAllocation'],
   cachingOpportunity: ['variant', 'relation', 'format', 'relations', 'operator', 'executionIds', 'totalReadBytes'],
   jobFailureRate: ['failedJobs', 'totalJobs', 'failedTasks', 'totalTasks', 'avgJobDurationMs', 'taskFailureRate'],
   configAudit: ['property'],
@@ -211,8 +211,8 @@ const EVIDENCE_KEYS = {
     'groupIndex',
   ],
   smallFiles: ['executionId', 'stageIds', 'fileCount', 'direction', 'nodeName'],
-  underBroadcast: ['executionId', 'stageIds', 'largerSideBytes'],
-  overBroadcast: ['executionId', 'stageIds'],
+  underBroadcast: ['executionId', 'stageIds', 'largerSideBytes', 'broadcastThreshold'],
+  overBroadcast: ['executionId', 'stageIds', 'broadcastThreshold'],
 }                                                                                    ;
 
 // The other direction: an evidence field EVIDENCE_KEYS doesn't list fails here.

package/vendor-core/finding-presentation.js

@@ -8,7 +8,7 @@
 // detectors.ts is type-only, so it is erased at build time. A detector's scope, order and emits
 // list stay on its DETECTORS entry; renderers get them through detectorInfoByType().
                                                    
-                                                      
+                                                                  
                                                          
 
                                                              
@@ -43,7 +43,9 @@ const SKEW_JOIN_ALREADY_ON = 'AQE skew-join handling is already on, so salt the
 const SKEW_JOIN_AQE_OFF = 'AQE is off, so enable it (spark.sql.adaptive.enabled) for skew-join handling to apply; otherwise salt the key or repartition on a better key.';
 
 // The skew-join generic line, worded per the row's remediation: AQE logged off, switch already on, or neither.
-function skewJoinGeneric(f                                 , unset        )         {
+function skewJoinGeneric(f                                                      , unset        )         {
+  if (f.origin === 'inputScan') return 'Uneven input files: compact small files or split large ones (lower spark.sql.files.maxPartitionBytes).';
+  if (f.origin === 'other') return 'Work is uneven across tasks: salt the key or repartition on a better key.';
   if (f.remediation?.some((r) => r.key === 'spark.sql.adaptive.enabled')) return SKEW_JOIN_AQE_OFF;
   return switchAlreadyOn(f, SKEW_JOIN_KEY) ? SKEW_JOIN_ALREADY_ON : unset;
 }
@@ -120,8 +122,9 @@ export const FINDING_PRESENTATION
     tag: 'TINY',
     thresholdSummary: (t) => `${t.minTasks}+ tasks with a median of ${t.maxP50}ms or less and a P95 of ${t.maxP95}ms or less`,
     actionLabel: () => 'Coalesce small tasks',
-    // The shuffle-vs-no-shuffle fix isn't a Finding field, so one sentence covers both.
-    genericRecommendation: () => 'Scheduler overhead may dominate: lower spark.sql.shuffle.partitions, or coalesce down to fewer, larger tasks.',
+    genericRecommendation: (f) => (f.reads != null && f.reads !== 'shuffle'
+      ? 'Scheduler overhead may dominate: coalesce down to fewer, larger tasks.'
+      : 'Scheduler overhead may dominate: lower spark.sql.shuffle.partitions, or coalesce down to fewer, larger tasks.'),
   },
 
   shuffle: {
@@ -129,7 +132,14 @@ export const FINDING_PRESENTATION
     tag: 'SHFL',
     thresholdSummary: (t) => `stage shuffle read above ${t.minBytes / 1048576} MiB`,
     actionLabel: () => 'Reduce shuffle size',
-    genericRecommendation: () => 'Raise spark.sql.shuffle.partitions, or use a broadcast join for the smaller side.',
+    genericRecommendation: (f) => {
+      switch (f.partitions) {
+        case 'sufficient': return 'The tasks are already a good size, so more partitions will not help: use a broadcast join for the smaller side.';
+        case 'aqeCoalesced': return 'AQE coalesced the shuffle: lower spark.sql.adaptive.advisoryPartitionSizeInBytes, or use a broadcast join for the smaller side.';
+        case 'ownPartitioning': return "spark.sql.shuffle.partitions is already high enough, so raise this stage's own partition count (its repartition(n) or RDD parallelism), or use a broadcast join for the smaller side.";
+        default: return 'Raise spark.sql.shuffle.partitions, or use a broadcast join for the smaller side.';
+      }
+    },
   },
   partitionSizing: {
     name: 'partition sizing',
@@ -146,7 +156,9 @@ export const FINDING_PRESENTATION
     genericRecommendation(f) {
       switch (f.rule) {
         case 'shufflePartitionSkew': return skewJoinGeneric(f, 'For join skew, enable AQE skew-join handling (spark.sql.adaptive.skewJoin.enabled); otherwise salt the key or repartition on a better key.');
-        case 'lowShuffleParallelism': return switchAlreadyOn(f, 'spark.sql.shuffle.partitions')
+        case 'lowShuffleParallelism':
+          if (f.partitions === 'aqeCoalesced') return 'AQE coalesced the shuffle into few tasks: lower spark.sql.adaptive.advisoryPartitionSizeInBytes so each partition is smaller.';
+          return switchAlreadyOn(f, 'spark.sql.shuffle.partitions')
           ? "spark.sql.shuffle.partitions is already high enough, so raise this stage's own partition count (its repartition(n) or RDD parallelism) so each partition is smaller."
           : 'Raise spark.sql.shuffle.partitions so each partition is smaller.';
         case 'maxPartitionTooBig': return 'Repartition to break up the oversized partition before this stage.';
@@ -161,7 +173,9 @@ export const FINDING_PRESENTATION
     thresholdSummary: (t) => `single-task disk spill above ${t.singleTaskDiskGiB} GiB`,
     actionLabel: () => 'Reduce spill',
     // The skew/volume classification isn't a Finding field, so one sentence covers both.
-    genericRecommendation: () => 'If the spill is skew-driven, fix task skew first: adding memory will not help. Otherwise raise spark.sql.shuffle.partitions or increase executor memory.',
+    genericRecommendation: (f) => (f.reads != null && f.reads !== 'shuffle'
+      ? 'If the spill is skew-driven, fix task skew first: adding memory will not help. Otherwise increase executor memory or process less data per task.'
+      : 'If the spill is skew-driven, fix task skew first: adding memory will not help. Otherwise raise spark.sql.shuffle.partitions or increase executor memory.'),
   },
 
   gc: {
@@ -219,14 +233,18 @@ export const FINDING_PRESENTATION
     tag: 'SLOW',
     thresholdSummary: () => 'a stage running far longer than its peers, not attributable to a single slow host',
     actionLabel: () => 'Profile slow stage',
-    genericRecommendation: () => 'Often a partition-count problem: raise parallelism via spark.sql.shuffle.partitions or spark.default.parallelism, or check for a large per-task data volume driving heavy shuffle and spill.',
+    genericRecommendation: (f) => f.reads === 'input'
+      ? 'Often too few or too uneven input partitions: check input file sizes and lower spark.sql.files.maxPartitionBytes, or look for a large per-task data volume driving heavy spill.'
+      : f.reads === 'other'
+        ? 'Check what the stage computes and for a large per-task data volume driving heavy spill.'
+        : 'Often a partition-count problem: raise parallelism via spark.sql.shuffle.partitions or spark.default.parallelism, or check for a large per-task data volume driving heavy shuffle and spill.',
   },
   straggler: {
     name: 'straggling task',
     tag: 'STRAG',
     thresholdSummary: () => 'one or more tasks finishing far after the rest of their stage',
     actionLabel: () => 'Fix stragglers',
-    genericRecommendation: () => 'Rule out a GC pause or a slow shuffle fetch before assuming a hardware issue. If a skewed key is the real cause, that is a candidate for AQE\'s skew-join handling.',
+    genericRecommendation: (f) => `Rule out a GC pause or a slow shuffle fetch before assuming a hardware issue. If uneven data is the cause: ${skewJoinGeneric(f, 'for join-driven skew, enable AQE skew-join handling (spark.sql.adaptive.skewJoin.enabled); otherwise salt the key or repartition on a better key.')}`,
   },
   speculationWaste: {
     name: 'speculation waste',
@@ -240,7 +258,9 @@ export const FINDING_PRESENTATION
     tag: 'COLD',
     thresholdSummary: (t) => `the first stage waiting over ${t.gapSeconds}s for an executor`,
     actionLabel: () => 'Pre-warm cluster',
-    genericRecommendation: () => 'Keep a warm pool of idle executors, or if using dynamic allocation, raise the minimum/initial executor count so it does not scale up from zero.',
+    genericRecommendation: (f) => (f.dynamicAllocation === 'off'
+      ? 'Keep a warm pool of idle executors: dynamic allocation is off, so no executor-count property applies.'
+      : 'Keep a warm pool of idle executors, or if using dynamic allocation, raise the minimum/initial executor count so it does not scale up from zero.'),
   },
 
   memoryUtilization: {
@@ -322,7 +342,9 @@ export const FINDING_PRESENTATION
     tag: 'CHRN',
     thresholdSummary: (t) => `over ${shareLabel(t.warningPct)} of executors living under ${t.shortLivedMs / 60000} minutes`,
     actionLabel: () => 'Reduce autoscaling churn',
-    genericRecommendation: () => 'This looks like wasteful re-provisioning rather than normal scale-down: consider raising spark.dynamicAllocation.executorIdleTimeout or widening the minExecutors/maxExecutors bounds to reduce flapping.',
+    genericRecommendation: (f) => (f.dynamicAllocation === 'off'
+      ? 'Dynamic allocation is off, so the churn comes from executors lost or preempted: check the cluster manager\'s preemption and executor-loss logs.'
+      : 'This looks like wasteful re-provisioning rather than normal scale-down: consider raising spark.dynamicAllocation.executorIdleTimeout or widening the minExecutors/maxExecutors bounds to reduce flapping.'),
   },
 
   configAudit: CONFIG_AUDIT_PRESENTATION,
@@ -349,14 +371,18 @@ export const FINDING_PRESENTATION
     tag: 'PLAN',
     thresholdSummary: () => 'a join below the configured size floor that skipped broadcast',
     actionLabel: () => 'Use broadcast join',
-    genericRecommendation: () => 'This could have been a broadcast join: consider a broadcast() hint or raising spark.sql.autoBroadcastJoinThreshold.',
+    genericRecommendation: (f) => (f.broadcastThreshold === 'notLimiting'
+      ? 'The threshold already admits the smaller side, so it is not what stopped the broadcast: consider a broadcast() hint or collecting table statistics.'
+      : 'This could have been a broadcast join: consider a broadcast() hint or raising spark.sql.autoBroadcastJoinThreshold.'),
   },
   overBroadcast: {
     name: 'oversized broadcast join',
     tag: 'PLAN',
     thresholdSummary: (t) => `a broadcast over ${t.overBroadcastBytes / 1073741824} GiB`,
     actionLabel: () => 'Fix oversized broadcast',
-    genericRecommendation: (f) => (switchAlreadyOn(f, 'spark.sql.autoBroadcastJoinThreshold')
+    genericRecommendation: (f) => (f.broadcastThreshold === 'notLimiting'
+      ? 'The configured threshold is below this broadcast, so remove the broadcast() hint that forced it.'
+      : switchAlreadyOn(f, 'spark.sql.autoBroadcastJoinThreshold')
       ? 'Automatic broadcast is already disabled, so remove the broadcast() hint that forced it.'
       : 'Check for a misapplied broadcast hint or a misconfigured spark.sql.autoBroadcastJoinThreshold.'),
   },

package/vendor-core/finding-types.js

@@ -79,7 +79,22 @@
 
 // ── Per-stage detectors ─────────────────────────────────────────────────────
 
-                                                
+/** What a skewed stage reads, which decides the fix: 'shuffleJoin' (a shuffle feeding a join, where
+ * AQE skew-join handling applies), 'inputScan' (uneven input files) or 'other'. */
+                                                               
+
+/** What a stage reads, by the dominant side: a shuffle, input files, or neither. */
+                                                       
+
+/** Why a shuffle finding's partition-count advice is or is not given: 'raise' (the property limits
+ * the stage), 'sufficient' (tasks are already a good size), 'aqeCoalesced' (AQE merged the
+ * partitions, so the advisory size is the lever) or 'ownPartitioning' (the property is already high
+ * enough, so the stage's own repartition(n) or RDD parallelism is). */
+                                                                                            
+
+                               
+                      
+ 
                                                                             
 
                                      
@@ -90,16 +105,24 @@
                       
  
 
-                                                   
+                                  
+                                 
+ 
                                                                                      
 
                                           
                                                                                 
+                                                    
+                      
+                                                                                                           
+                                 
  
                                                                                                              
 
                                 
                                                 
+                                                                              
+                     
  
                                                                                
 
@@ -124,7 +147,10 @@
  
                                                                                         
 
-                                                         
+                                        
+                                                                                     
+                     
+ 
                                                                                                        
 
                                       
@@ -151,6 +177,8 @@
                         
                            
                          
+                                                                                     
+                      
  
                                                                                            
 
@@ -167,7 +195,10 @@
                     
  
 
-                                                    
+                                   
+                                                                                  
+                     
+ 
                                                                                         
 
 // ── App-level detectors ─────────────────────────────────────────────────────
@@ -176,7 +207,10 @@
 // valueText is always 'missing': the ApplicationEnd event the log lacks.
                                                                                                     
 
-                                                     
+                                    
+                                                                                                
+                                   
+ 
                                                                                            
 
                                       
@@ -231,6 +265,8 @@
 
                                            
                                   
+                                                                                           
+                                   
  
                                                                                                                 
 
@@ -296,13 +332,21 @@
                    
  
                                                                                                               
+
+/** How the effective spark.sql.autoBroadcastJoinThreshold relates to the finding: 'limits' (the
+ * property decided it, or is unknown), 'notLimiting' (already admits, or already below, the
+ * broadcast, so something else decided it) or 'disabled' (-1). */
+                                                                       
 
                                                                      
                           
+                                          
  
                                                                                                                           
 
-                                                        
+                                                                    
+                                          
+ 
                                                                                                                        
 
 // ── Unions ──────────────────────────────────────────────────────────────────

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

@@ -119,14 +119,18 @@ export function createMcpServer({ thresholds }
       maxRegressionPct: z.number().optional(), regressionMetric: z.string().optional(), failOnIntroduced: z.string().optional(),
       regressionBudgets: z.array(z.object({ metric: z.string(), maxPct: z.number().nonnegative() })).optional()
         .describe('Further regression budgets, one per metric (the CLI\'s repeated --regression-budget). A metric can be budgeted once across this list and maxRegressionPct/regressionMetric.'),
+      stageRegressionBudgets: z.array(z.object({ metric: z.string(), maxPct: z.number().nonnegative() })).optional()
+        .describe('Per paired stage (needs sourceB/runIdB): fail when any eligible pair\'s metric (executorRunTime, executorCpuTime, memoryBytesSpilled, diskBytesSpilled, shuffleReadBytes, shuffleWriteBytes) regressed by more than maxPct. One entry per metric. Inconclusive when no stage pairs.'),
+      stageQualities: z.array(z.enum(['exact', 'structural', 'aligned'])).optional()
+        .describe('Pair qualities the stage budgets read. Default exact and structural: an aligned pair may compare different work.'),
     },
   }, ({
     source, runId, runIdB, sourceB,
     maxRuntimeMs, maxSpillGb, maxSkewRatio, maxFailedTaskRatePct, minEfficiencyPct,
-    maxRegressionPct, regressionMetric, failOnIntroduced, regressionBudgets,
+    maxRegressionPct, regressionMetric, failOnIntroduced, regressionBudgets, stageRegressionBudgets, stageQualities,
   }) => toolResult(evaluateBudgetsForRun(
     { source, runId },
-    { maxRuntimeMs, maxSpillGb, maxSkewRatio, maxFailedTaskRatePct, minEfficiencyPct, maxRegressionPct, regressionMetric, failOnIntroduced, regressionBudgets },
+    { maxRuntimeMs, maxSpillGb, maxSkewRatio, maxFailedTaskRatePct, minEfficiencyPct, maxRegressionPct, regressionMetric, failOnIntroduced, regressionBudgets, stageRegressionBudgets, stageQualities },
     (runIdB || sourceB) ? { runId: runIdB, source: sourceB } : undefined,
     { thresholds },
   )));

package/vendor-core/mcp-tools.js

@@ -13,7 +13,7 @@ import { buildComparisonOutput,                       } from './comparison-outpu
 import { compileNormalizePatterns } from './stage-alignment.js';
 import { runOutputBlocks } from './run-output.js';
 import { evaluateBudgets,                                       } from './cli/budgets.js';
-import { combineRegressionBudgets } from './cli/regression-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';
@@ -416,6 +416,15 @@ export async function evaluateBudgetsForRun(
   } 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),

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/run-comparison.js

@@ -38,6 +38,7 @@ import { summarizeRunOutcome } from './run-outcome.js';
                                          
                                          
                                                              
+                                                           
                             
                                                                              
                             
@@ -408,6 +409,7 @@ export function compareRuns(
     unmatched: alignment.unmatched,
     replanned: alignment.replanned,
     bookkeepingStageIds: alignment.bookkeepingStageIds,
+    executionAlignment: alignment.executionAlignment,
     metrics: metricDeltas(baseSnap, candSnap),
     findings: findingsDelta(baseSnap, candSnap),
     stageSkew: stageSkewDeltas(baseSnap, candSnap, alignment.pairs),

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 };
+}