sparkforensics-cli 0.1.0

package/vendor-core/mcp-tools.js

@@ -0,0 +1,331 @@
+import { resolve as resolvePath } from 'node:path';
+import { existsSync, statSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+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 { redactAppIdentity, redactComparison } from './redact.js';
+import { computeWallClock } from './wall-clock.js';
+import { analyze } from './analyzer.js';
+import { buildComparison, renderComparisonMarkdown,                        } from './run-comparison.js';
+import { evaluateBudgets,                                       } from './cli/budgets.js';
+                                                                  
+
+                                                                                                     
+// NOTE on a deviation from the plan's literal text: the plan defines RunRef as
+// `{ runId?: string } & Partial<RunSource>` (path/shsBaseUrl/appId/attemptId
+// flattened directly onto the object). Every real call site disagrees with
+// that shape: resolveOrCreateRun's own destructuring (`{ source, runId } = {}`
+// below), both mcp-server-factory.ts call sites (`compareRuns({ runId: runIdA,
+// source: sourceA }, ...)`), and every resolveOrCreateRun/compareRuns call in
+// tests/mcp-tools.test.js all pass a *nested* `source` key, never a flattened
+// path/shsBaseUrl directly on the ref object. Widened to match that real,
+// long-standing shape instead of reshaping every working call site (or every
+// test) to fit the literal text.
+                                                            
+                             
+                
+                                                                                     
+                                                                          
+                                                                                 
+                                                                          
+                                                                               
+                                                                  
+                                                    
+                            
+                                                                        
+                                                                           
+                                                                         
+                                                                         
+                                                                       
+                       
+ 
+// The plan's Produces list types compareRuns's return as `CompareRunsResult`
+// (run-comparison.ts's raw comparison shape: baselineLabel/candidateLabel/
+// stageSkew/baseStages/candStages/...). compareRuns below actually returns a
+// distinct, smaller MCP-facing projection of that (runIdA/runIdB/
+// findingsDelta/metricDeltas/confidence/reason/matchedCoverage); it never
+// had baselineLabel, stageSkew, baseStages, or candStages. Introduced this
+// interface to match the real returned shape rather than casting a literal
+// that's actually missing several required CompareRunsResult properties.
+                                       
+                 
+                 
+                                               
+                                             
+                                              
+                                      
+                                                        
+ 
+
+function envInt(name        , fallback        )         {
+  const v = Number(process.env[name]);
+  return Number.isFinite(v) && v > 0 ? v : fallback;
+}
+
+// `touch()` below does a full Map delete+re-insert per cache hit to maintain
+// LRU order: O(n) per touch, fine at this small cap but worth re-checking
+// the cost if this cap is ever raised significantly.
+const CACHE_CAP = envInt('SPARKFORENSICS_MCP_CACHE_CAP', 8);
+const CACHE_TTL_MS = envInt('SPARKFORENSICS_MCP_CACHE_TTL_MS', 15 * 60 * 1000);
+
+                                                                                 
+
+const byRunId = new Map                    ();   // runId -> { appModel, cacheKey, lastAccess }
+const byCacheKey = new Map                (); // cacheKey -> runId
+const pendingByCacheKey = new Map                                                        (); // cacheKey -> in-flight Promise<{runId, appModel}>
+
+export function pathCacheKey(path        )         {
+  const resolved = resolvePath(path);
+  if (!existsSync(resolved)) throw mcpError('invalid-event-log', `No such file: ${resolved}`);
+  // Size narrows a same-millisecond mtime collision; ctime narrows the case
+  // where a copy tool (rsync --preserve-times, tar) restores an identical
+  // mtime and size for different content: ctime can't be set by the copying
+  // tool, so it still reflects the real time the file landed on disk.
+  const { mtimeMs, ctimeMs, size } = statSync(resolved);
+  return `path:${resolved}:${mtimeMs}:${ctimeMs}:${size}`;
+}
+
+function shsCacheKey({ shsBaseUrl, appId, attemptId }                                                           )         {
+  return `shs:${shsBaseUrl}:${appId}:${attemptId ?? ''}`;
+}
+
+function touch(runId        )       {
+  const entry = byRunId.get(runId);
+  // Defensive only for type-narrowing: every call site below touches a runId
+  // it (or getCachedAppModel) has already confirmed present.
+  if (!entry) return;
+  byRunId.delete(runId);
+  entry.lastAccess = Date.now();
+  byRunId.set(runId, entry);
+}
+
+function deleteRunEntry(id        , entry            )       {
+  byRunId.delete(id);
+  if (byCacheKey.get(entry.cacheKey) === id) byCacheKey.delete(entry.cacheKey);
+}
+
+function evictStale()       {
+  const now = Date.now();
+  for (const [id, entry] of byRunId) {
+    if (now - entry.lastAccess > CACHE_TTL_MS) {
+      deleteRunEntry(id, entry);
+    }
+  }
+}
+
+function evictOverflow()       {
+  while (byRunId.size > CACHE_CAP) {
+    const oldestId = byRunId.keys().next().value;
+    // Defensive only for type-narrowing: the while condition guarantees
+    // byRunId is non-empty here, so .keys().next() always has a value.
+    if (oldestId === undefined) break;
+    const entry = byRunId.get(oldestId);
+    if (entry) deleteRunEntry(oldestId, entry);
+  }
+}
+
+export function getCachedAppModel(runId        )           {
+  evictStale();
+  const entry = byRunId.get(runId);
+  if (!entry) throw mcpError('run-not-found', `No cached run for runId ${runId}.`);
+  touch(runId);
+  return entry.appModel;
+}
+
+async function resolveFromPath(path        )                    {
+  const { appModel, skippedLines } = await collectRun(path);
+  appModel.evidenceAvailability = deriveEvidenceAvailability(appModel, { skippedLines });
+  return appModel;
+}
+
+export async function resolveOrCreateRun(
+  { source, runId }         = {},
+  { fetchImpl = fetch, maxArchiveBytes = DEFAULT_MAX_ARCHIVE_BYTES, idleTimeoutMs = DEFAULT_IDLE_TIMEOUT_MS } 
+                                                                                   = {},
+)                                                 {
+  evictStale();
+  if (runId) {
+    return { runId, appModel: getCachedAppModel(runId) };
+  }
+  if (!source) throw mcpError('access-or-upstream-failure', 'Provide either source or runId.');
+
+  // `'path' in source`, not `source.path`: RunSource's two variants share no
+  // common property, so a plain `.path` access doesn't type-check on the
+  // union. Equivalent at runtime to the original truthy check for every real
+  // caller (a path source's `path` is always a non-empty resolved filesystem
+  // path; it's never the empty string).
+  const cacheKey = 'path' in source ? pathCacheKey(source.path) : shsCacheKey(source);
+  const cached = byCacheKey.get(cacheKey);
+  if (cached && byRunId.has(cached)) {
+    touch(cached);
+    return { runId: cached, appModel: byRunId.get(cached) .appModel };
+  }
+
+  // Concurrent calls for the same not-yet-cached source (e.g. two tool calls
+  // in flight for the same path) must await one shared parse rather than each
+  // racing to insert their own cache entry: otherwise every racer's insert
+  // after the first is an orphaned entry (unreachable via cacheKey, wasting a
+  // cache slot until TTL/overflow).
+  const pending = pendingByCacheKey.get(cacheKey);
+  if (pending) return pending;
+
+  const resolution = (async () => {
+    try {
+      const appModel = 'path' in source
+        ? await resolveFromPath(source.path)
+        : await resolveFromShs(source.shsBaseUrl, source.appId, source.attemptId, { fetchImpl, maxArchiveBytes, idleTimeoutMs });
+
+      const newRunId = randomUUID();
+      byRunId.set(newRunId, { appModel, cacheKey, lastAccess: Date.now() });
+      byCacheKey.set(cacheKey, newRunId);
+      evictOverflow();
+      return { runId: newRunId, appModel };
+    } finally {
+      pendingByCacheKey.delete(cacheKey);
+    }
+  })();
+  pendingByCacheKey.set(cacheKey, resolution);
+  return resolution;
+}
+
+export function diagnoseRun(runId        , opts    
+                                                                                                          
+                                                           
+ )   
+                                                              
+                                                                       
+                                                                                                                {
+  const appModel = getCachedAppModel(runId);
+  const findingsFilter = toFindingsFilter(opts?.impactBand, opts?.type, opts?.stageId);
+  const { json, markdown } = buildEvidenceReport(appModel, { redact: opts?.redact, markdown: opts?.markdown, findingsFilter });
+  const include = opts?.include ?? [];
+  return {
+    runId, findings: json.findings, recommendations: json.recommendations, cleanChecks: json.cleanChecks,
+    runComplete: appModel.app?.endTime != null,
+    ...(include.includes('summary') ? { summary: json.summary } : {}),
+    ...(include.includes('evidenceAvailability') ? { evidenceAvailability: json.evidenceAvailability } : {}),
+    ...(include.includes('detectors') ? { detectors: json.detectors } : {}),
+    ...(opts?.markdown ? { markdown } : {}),
+  };
+}
+
+export function getFindingEvidence(
+  runId        , findingId        , opts                       ,
+)                                         {
+  const appModel = getCachedAppModel(runId);
+  const { json } = buildEvidenceReport(appModel, { redact: opts?.redact, markdown: false });
+  const finding = json.findings.find((f) => f.id === findingId);
+  if (!finding) throw mcpError('finding-not-found', `No finding ${findingId} on run ${runId}.`);
+  return { runId, finding };
+}
+
+function hasCompleteInterval(app                     )          {
+  return Number.isFinite(app?.startTime) && Number.isFinite(app?.endTime) && (app?.endTime ?? 0) > (app?.startTime ?? 0);
+}
+
+export function getRunSummary(runId        , opts                       )             {
+  const appModel = getCachedAppModel(runId);
+  const { app, stages, jobs, sql, executors } = appModel;
+  const durationMs = hasCompleteInterval(app) ? computeWallClock(app, stages).total : null;
+  // No buildEvidenceReport call here to redact (see the type comment above),
+  // so reuse redact.ts's app-id + host-token pseudonymization directly via
+  // redactAppIdentity(). Passing name/sparkVersion through it (not just id)
+  // matters because app.name is free text and can itself carry a host/IP token.
+  const rawApp = { id: app?.id ?? null, name: app?.name ?? null, sparkVersion: app?.sparkVersion ?? null };
+  const redactedApp = opts?.redact ? redactAppIdentity(rawApp) : rawApp;
+  return {
+    runId,
+    app: redactedApp,
+    stageCount: stages.size,
+    jobCount: jobs.size,
+    sqlExecutionCount: sql.size,
+    executorCount: { added: executors.added.length, removed: executors.removed.length },
+    durationMs,
+    runComplete: app?.endTime != null,
+  };
+}
+
+// Shared by compareRuns and evaluateBudgetsForRun: both need a resolved run's
+// finding catalog (same analyze() call shape) before doing anything else with it.
+async function resolveAndAnalyze(ref        )                                                                     {
+  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,
+  );
+  return { runId, appModel, catalog };
+}
+
+export async function compareRuns(
+  a        , b        , opts                                           ,
+)                                                        {
+  const [
+    { runId: runIdA, appModel: appModelA, catalog: catalogA },
+    { runId: runIdB, appModel: appModelB, catalog: catalogB },
+  ] = await Promise.all([resolveAndAnalyze(a), resolveAndAnalyze(b)]);
+
+  // buildComparison's captureSnapshot step uses an empty taskDataCache: that
+  // arg only feeds the interactive stage-detail drill-down modal, which none
+  // of compareRuns/matchStages/metricDeltas/findingsDelta/stageSkewDeltas/
+  // stageList read. Findings/metrics come from `catalog` (already computed
+  // via `analyze()` above) and from `appModel.stages`/`sql` (which already
+  // carry plan-tree data), both fully populated regardless. Produces
+  // identical comparison output to the dashboard's session-cache snapshots;
+  // the MCP tool just never exposes per-task drill-down, so there's nothing
+  // to prefetch into it.
+  const built = buildComparison(
+    { label: runIdA, appModel: appModelA, catalog: catalogA },
+    { label: runIdB, appModel: appModelB, catalog: catalogB },
+  );
+  // Stage names throughout `built` (findings.introduced/resolved[].stages,
+  // baseStages/candStages[].name) 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;
+
+  return {
+    runIdA,
+    runIdB,
+    findingsDelta: result.findings,
+    metricDeltas: result.metrics,
+    confidence: result.confidence,
+    reason: result.reason,
+    matchedCoverage: result.matchedCoverage,
+    ...(opts?.markdown ? { markdown: renderComparisonMarkdown(result) } : {}),
+  };
+}
+
+export async function evaluateBudgetsForRun(
+  primary        ,
+  budgets               ,
+  secondary         ,
+)                                                                                                {
+  // Mirrors the CLI's own --regression-metric/--max-regression-pct pairing
+  // guard (bin/sparkforensics-analyze.mjs): unlike the CLI, this tool never
+  // defaults regressionMetric on the caller's behalf, so seeing it set here
+  // unambiguously means the caller asked for a regression check and forgot
+  // the threshold — evaluateBudgets() would otherwise skip the check with no
+  // signal at all.
+  if (budgets.regressionMetric !== undefined && budgets.maxRegressionPct === undefined) {
+    throw mcpError('access-or-upstream-failure', 'regressionMetric requires maxRegressionPct.');
+  }
+  const [{ runId, appModel, catalog }, second] = await Promise.all([
+    resolveAndAnalyze(primary),
+    secondary ? resolveAndAnalyze(secondary) : Promise.resolve(undefined),
+  ]);
+
+  let comparison                               ;
+  if (second) {
+    comparison = buildComparison(
+      { label: runId, appModel, catalog },
+      { label: second.runId, appModel: second.appModel, catalog: second.catalog },
+    );
+  }
+
+  const { results, violated, inconclusive } = evaluateBudgets({ appModel, catalog, budgets, comparison });
+
+  return { runId, results, violated, inconclusive };
+}

package/vendor-core/model-assembler.js

@@ -0,0 +1,76 @@
+             
+           
+               
+        
+               
+           
+                
+      
+                
+                    
+
+// Worker-message → appModel assembly. Shared by file-load and SHS-URL-load paths,
+// which previously carried byte-identical callback blocks. Pure model mutation:
+// analysis/render/persist stay in the caller via the onDone/onProgress/onError hooks.
+export function createModelCallbacks(
+  appModel          ,
+  { onProgress, onDone, onError }   
+                                         
+                                     
+                                      
+   ,
+) {
+  return {
+    onProgress,
+    onApp(data         ) { appModel.app = data                ; },
+    onStage(data         ) {
+      const stage = data         ;
+      appModel.stages.set(stage.id, stage);
+    },
+    onSql(data         ) {
+      // Full overwrite, not a merge: safe only because `planTree` (set by
+      // onSqlPlan below, from a separate 'sqlPlan' message) is never present
+      // on a 'sql' message's data. That in turn relies on
+      // SparkListenerSQLAdaptiveExecutionUpdate always preceding
+      // SparkListenerSQLExecutionEnd for the same execution (Spark emits a
+      // re-plan mid-run, never after the query finishes); see
+      // applyAdaptiveExecutionUpdate in event-handlers.ts. A future producer
+      // of 'sql' messages that could arrive after onSqlPlan would need this
+      // to merge instead of overwrite.
+      const event = data                                       ;
+      appModel.sql.set(event.id, data                );
+      for (const stageId of (event.stageIds ?? [])) {
+        const stage = appModel.stages.get(stageId);
+        if (stage) stage.sqlExecutionId = event.id;
+      }
+    },
+    onSqlPlan(data         ) {
+      const event = data                                               ;
+      const exec = appModel.sql.get(event.executionId);
+      if (exec) exec.planTree = event.planTree;
+    },
+    onExecutor(data         ) {
+      const event = data                 ;
+      if (event.kind === 'added') appModel.executors.added.push(event);
+      else appModel.executors.removed.push(event);
+    },
+    onJob(data         ) {
+      const job = data       ;
+      appModel.jobs.set(job.id, job);
+    },
+    onRunAggregates(data         ) { appModel.runAggregates = data                 ; },
+    // Patch per-stage executorMetrics posted once before `done`: see the
+    // parser worker's SparkListenerStageExecutorMetrics handler (those events
+    // arrive after StageCompleted, so the stage message itself carried an
+    // empty map). `data` is a Map<stageId, Map<execId, metrics>>.
+    onStageExecutorMetrics(data         ) {
+      if (!(data instanceof Map)) return;
+      const metricsByStage = data                                     ;
+      for (const [stageId, execMetrics] of metricsByStage) {
+        const stage = appModel.stages.get(stageId);
+        if (stage) stage.executorMetrics = execMetrics;
+      }
+    },
+    onDone, onError,
+  };
+}

package/vendor-core/occupancy.js

@@ -0,0 +1,202 @@
+// src/occupancy.ts
+// Occupancy-weighted wall-clock attribution (N1 redesign). Replaces the old
+// CPM pass over parentIds for per-finding impact estimation. No graph, no
+// parentIds traversal: every stage's wall-clock claim is apportioned purely
+// from its own observed window and how much it overlapped with other
+// stages.
+import { mergeIntervals } from './wall-clock.js';
+
+                                 
+             
+                       
+                       
+                           
+                           
+ 
+
+function durationMs(s                )         {
+  return (s.completedAt ?? 0) - (s.submittedAt ?? 0);
+}
+
+// Average-concurrency proxy, held constant across the stage's whole active
+// window: no per-task timestamps exist outside the parser worker to do
+// better (see the redesign spec's "Explicitly rejected" section).
+function coreWeight(s                )         {
+  const d = durationMs(s);
+  return d > 0 ? (s.executorRunTime ?? 0) / d : 0;
+}
+
+/**
+ * Sweeps every stage's observed [submittedAt, completedAt) window and splits
+ * each instant's wall-clock among the stages active at that instant,
+ * proportional to coreWeight(S). Stages with duration(S) <= 0 are excluded
+ * entirely: they get no key in the returned map. When every active stage in
+ * an interval has coreWeight 0 (no executorRunTime data), the interval is
+ * split equally among them instead of everyone getting 0: a lone active
+ * stage must still resolve to occupying its own whole window regardless of
+ * whether core-time data exists for it.
+ */
+export function computeOccupancyMs(stages                             )                      {
+  const valid = [...stages.values()].filter((s) => durationMs(s) > 0);
+  const occupancy = new Map                ();
+  for (const s of valid) occupancy.set(s.id, 0);
+  if (valid.length === 0) return occupancy;
+
+  const events                                                                   = [];
+  for (const s of valid) {
+    const w = coreWeight(s);
+    events.push({ time: s.submittedAt ?? 0, id: s.id, weight: w, isStart: true });
+    events.push({ time: s.completedAt ?? 0, id: s.id, weight: w, isStart: false });
+  }
+  events.sort((a, b) => a.time - b.time);
+
+  const active = new Map                (); // id -> coreWeight
+  let prevTime = events[0].time;
+  let i = 0;
+  while (i < events.length) {
+    const time = events[i].time;
+    if (time > prevTime && active.size > 0) {
+      const span = time - prevTime;
+      let totalWeight = 0;
+      for (const w of active.values()) totalWeight += w;
+      for (const [id, w] of active) {
+        const share = totalWeight > 0 ? w / totalWeight : 1 / active.size;
+        occupancy.set(id, (occupancy.get(id) ?? 0) + span * share);
+      }
+    }
+    while (i < events.length && events[i].time === time) {
+      const e = events[i];
+      if (e.isStart) active.set(e.id, e.weight);
+      else active.delete(e.id);
+      i++;
+    }
+    prevTime = time;
+  }
+  return occupancy;
+}
+
+/**
+ * Occupancy-share of a stage's own observed duration, gate(S) in [0, 1];
+ * 1.0 means the stage ran completely alone, 0 means it had zero executorRunTime
+ * while overlapping other, positive-weight stages (so it got no share of the
+ * shared window). Excludes stages with duration(S) <= 0 (no key in the result).
+ */
+export function computeGate(stages                             )                      {
+  const occupancyMs = computeOccupancyMs(stages);
+  const gate = new Map                ();
+  for (const s of stages.values()) {
+    const d = durationMs(s);
+    if (d <= 0) continue;
+    const occ = occupancyMs.get(s.id) ?? 0;
+    // Clamp for float round-off in the sweep; occupancy can never truly exceed duration.
+    gate.set(s.id, Math.min(1, occ / d));
+  }
+  return gate;
+}
+
+/**
+ * A physical floor on a stage's own duration: bounded below by its single
+ * longest task (unsplittable no matter how much parallelism exists) or by
+ * its total core-work spread across every core in the cluster, whichever is
+ * larger. totalCores <= 0 (no executor data) falls back to taskDurationMax
+ * alone.
+ */
+export function computeCeiling(stage                , totalCores        )         {
+  const taskDurationMax = stage.taskDurationMax ?? 0;
+  if (totalCores <= 0) return taskDurationMax;
+  const coreWork = stage.executorRunTime ?? 0;
+  return Math.max(taskDurationMax, coreWork / totalCores);
+}
+
+/**
+ * Caps a waste formula's raw claim at the portion of the stage's own
+ * observed duration that sits above its physical floor: a finding can never
+ * claim to recover more than that.
+ */
+export function clipToCeiling(wasteMsClaimed        , stage                , ceiling        )         {
+  const room = Math.max(0, durationMs(stage) - ceiling);
+  return Math.min(wasteMsClaimed, room);
+}
+
+                                     
+               
+                  
+ 
+
+export function computeOccupancy(
+  stages                             ,
+  totalCores        ,
+)                                  {
+  const gate = computeGate(stages);
+  const info = new Map                            ();
+  for (const s of stages.values()) {
+    const g = gate.get(s.id);
+    if (g === undefined) continue; // excluded from the sweep (duration <= 0)
+    info.set(s.id, { gate: g, ceiling: computeCeiling(s, totalCores) });
+  }
+  return info;
+}
+
+const SERIAL_GATE_THRESHOLD = 0.999;
+
+                                    
+                                
+                                           
+ 
+
+/**
+ * Per-finding estimate for a single-stage waste claim. Returns null when the
+ * stage was excluded from the sweep (duration <= 0): callers must fall back
+ * to a resourceOnly/informational basis with wallClock: null, never a fake
+ * {0, 0}.
+ */
+export function estimateSingleStage(
+  wasteMsClaimed        ,
+  stageId        ,
+  stages                             ,
+  info                                 ,
+)                           {
+  const stage = stages.get(stageId);
+  const stageInfo = info.get(stageId);
+  if (!stage || !stageInfo) return null;
+  const clipped = clipToCeiling(wasteMsClaimed, stage, stageInfo.ceiling);
+  if (stageInfo.gate >= SERIAL_GATE_THRESHOLD) {
+    return { basis: 'serial', wallClock: { low: clipped, high: clipped } };
+  }
+  return { basis: 'contended', wallClock: { low: clipped * stageInfo.gate, high: clipped } };
+}
+
+/**
+ * Sum-then-cap over a finding's own stages: the union of the finding's own
+ * stage windows bounds the joint claim, so two overlapping stages' waste
+ * can't be double-counted. Returns null only when every one of the
+ * finding's stages was excluded from the sweep.
+ */
+export function estimateMultiStage(
+  stageIds          ,
+  wasteMsByStage                     ,
+  stages                             ,
+  info                                 ,
+)                           {
+  const perStage                      = [];
+  const intervals                     = [];
+  for (const id of stageIds) {
+    const est = estimateSingleStage(wasteMsByStage.get(id) ?? 0, id, stages, info);
+    if (!est) continue;
+    perStage.push(est);
+    const stage = stages.get(id) ;
+    intervals.push([stage.submittedAt ?? 0, stage.completedAt ?? 0]);
+  }
+  if (perStage.length === 0) return null;
+  const sumHigh = perStage.reduce((sum, e) => sum + e.wallClock.high, 0);
+  const sumLow = perStage.reduce((sum, e) => sum + e.wallClock.low, 0);
+  const unionMs = mergeIntervals(intervals).reduce((sum, [a, b]) => sum + (b - a), 0);
+  const high = Math.min(sumHigh, unionMs);
+  const low = Math.min(sumLow, unionMs);
+  // Numeric low === high isn't enough: the union cap can force that equality
+  // even when the constituent stages were individually contended (e.g. two
+  // fully-overlapping stages each at gate 0.5). Only claim 'serial' when
+  // every contributing per-stage estimate was itself serial.
+  const basis = perStage.every((e) => e.basis === 'serial') ? 'serial' : 'contended';
+  return { basis, wallClock: { low, high } };
+}