sparkforensics-cli 0.1.0

package/vendor-core/cli/budgets.js

@@ -0,0 +1,203 @@
+import { computeEfficiencyModel } from '../efficiency-model.js';
+import { computeSkewRatio, DETECTORS } from '../detectors.js';
+import { IMPACT_BAND_ORDER } from '../format-utils.js';
+                                                              
+                                                                 
+
+const IMPACT_BANDS = Object.keys(IMPACT_BAND_ORDER)                ;
+
+                                
+                                                                    
+                                                           
+                                                                                  
+ 
+                               
+                                                                                            
+                                              
+                                                
+                 
+ 
+
+const skewDetector = DETECTORS.find((d) => d.type === 'skew');
+const SKEW_MIN_TASKS_FOR_P95 = skewDetector .thresholds .minTasksForP95          ;
+
+function taskDataTrusted(appModel          )          {
+  const entry = appModel.evidenceAvailability?.entries?.find((e) => e.key === 'taskCoreTime');
+  return entry?.state === 'present';
+}
+
+// `Finding.value` is `number | string` (some detectors, e.g. stageFailed/
+// configAudit, put human-readable text there instead of a magnitude; see
+// types.ts). The 'spill' findings this is used for are always numeric; the
+// typeof guard below narrows without changing behavior for real input.
+function maxFindingValue(catalog           , type        )                {
+  const values = catalog
+    .filter((f) => f.type === type)
+    .map((f) => f.value ?? 0)
+    .filter((v)              => typeof v === 'number');
+  return values.length > 0 ? Math.max(...values) : null;
+}
+
+function checkRuntime(appModel          , maxRuntimeMs        )               {
+  const { startTime, endTime } = appModel.app ?? {};
+  if (startTime == null || endTime == null) {
+    return { name: 'max-runtime', status: 'inconclusive', detail: 'App start/end time not observed (run may not have finished).' };
+  }
+  const runtimeMs = endTime - startTime;
+  return runtimeMs > maxRuntimeMs
+    ? { name: 'max-runtime', status: 'violation', detail: `Runtime ${runtimeMs}ms exceeds budget ${maxRuntimeMs}ms.` }
+    : { name: 'max-runtime', status: 'pass', detail: `Runtime ${runtimeMs}ms within budget ${maxRuntimeMs}ms.` };
+}
+
+function checkSpill(appModel          , catalog           , maxSpillGb        )               {
+  if (!taskDataTrusted(appModel)) {
+    return { name: 'max-spill', status: 'inconclusive', detail: 'No trustworthy task-level evidence to measure spill.' };
+  }
+  const maxBytes = maxFindingValue(catalog, 'spill') ?? 0;
+  const budgetBytes = maxSpillGb * 1024 ** 3;
+  return maxBytes > budgetBytes
+    ? { name: 'max-spill', status: 'violation', detail: `Peak stage spill ${maxBytes} bytes exceeds budget ${budgetBytes} bytes.` }
+    : { name: 'max-spill', status: 'pass', detail: `Peak stage spill ${maxBytes} bytes within budget ${budgetBytes} bytes.` };
+}
+
+function checkSkew(appModel          , maxSkewRatio        )               {
+  if (!taskDataTrusted(appModel)) {
+    return { name: 'max-skew', status: 'inconclusive', detail: 'No trustworthy task-level evidence to measure skew.' };
+  }
+  const stages = [...(appModel.stages?.values() ?? [])];
+  if (stages.length === 0) {
+    return { name: 'max-skew', status: 'inconclusive', detail: 'No stage data observed in this event log.' };
+  }
+  // Recompute the true ratio per stage (not from the finding catalog): the
+  // skew detector floors its findings at thresholds.ratioWarn (3), so a
+  // budget stricter than that floor could never be enforced by reading
+  // catalog findings alone.
+  const ratios = stages
+    .map((stage) => computeSkewRatio(stage, SKEW_MIN_TASKS_FOR_P95))
+    .filter((r) => r !== null)
+    .map((r) => r.ratio);
+  if (ratios.length === 0) {
+    return { name: 'max-skew', status: 'inconclusive', detail: 'No stage has a measurable task-duration median.' };
+  }
+  const maxRatio = Math.max(...ratios);
+  return maxRatio > maxSkewRatio
+    ? { name: 'max-skew', status: 'violation', detail: `Peak stage skew ratio ${maxRatio} exceeds budget ${maxSkewRatio}.` }
+    : { name: 'max-skew', status: 'pass', detail: `Peak stage skew ratio ${maxRatio} within budget ${maxSkewRatio}.` };
+}
+
+function checkFailedTaskRate(appModel          , catalog           , maxPct        )               {
+  const finding = catalog.find((f) => f.type === 'jobFailureRate');
+  if (finding) {
+    const rate = (finding.taskFailureRate                      ) ?? 0;
+    return rate > maxPct
+      ? { name: 'max-failed-task-rate', status: 'violation', detail: `Task failure rate ${rate}% exceeds budget ${maxPct}%.` }
+      : { name: 'max-failed-task-rate', status: 'pass', detail: `Task failure rate ${rate}% within budget ${maxPct}%.` };
+  }
+  if ((appModel.jobs?.size ?? 0) === 0) {
+    return { name: 'max-failed-task-rate', status: 'inconclusive', detail: 'No job data observed in this event log.' };
+  }
+  // Jobs completed but the jobFailureRate detector never fired: job failure
+  // rate is below its own 10% info floor (src/detectors.js), so the task
+  // failure rate is implicitly low too. Known v1 limitation: a budget
+  // stricter than that floor cannot be enforced.
+  return { name: 'max-failed-task-rate', status: 'pass', detail: `No job-failure-rate finding: task failure rate is below the detector's reporting floor.` };
+}
+
+function checkEfficiency(appModel          , minPct        )               {
+  if (!taskDataTrusted(appModel)) {
+    return { name: 'min-efficiency', status: 'inconclusive', detail: 'No trustworthy task-level evidence to measure efficiency.' };
+  }
+  const model = computeEfficiencyModel({
+    app: appModel.app, stages: appModel.stages,
+    executorsAdded: appModel.executors.added, runAggregates: appModel.runAggregates,
+  });
+  if (model.wastagePct == null) {
+    return { name: 'min-efficiency', status: 'inconclusive', detail: 'Efficiency could not be computed (no available compute hours).' };
+  }
+  const efficiencyPct = 100 - model.wastagePct;
+  return efficiencyPct < minPct
+    ? { name: 'min-efficiency', status: 'violation', detail: `Efficiency ${efficiencyPct}% below budget ${minPct}%.` }
+    : { name: 'min-efficiency', status: 'pass', detail: `Efficiency ${efficiencyPct}% meets budget ${minPct}%.` };
+}
+
+function checkRegression(comparison                   , maxRegressionPct        , regressionMetric        )               {
+  const row = comparison.metrics.find((m) => m.key === regressionMetric);
+  if (!row || row.direction === 'unavailable' || row.baseline == null || row.delta == null) {
+    return { name: 'max-regression', status: 'inconclusive', detail: `Metric "${regressionMetric}" is unavailable for this comparison.` };
+  }
+  // A neutral-direction metric (inputBytes, outputBytes, taskCount,
+  // executorsAdded — see NEUTRAL_METRIC_KEYS in run-comparison.ts) measures
+  // workload volume, not performance: an increase isn't a regression, so a
+  // regression budget can't be meaningfully evaluated against it either way.
+  if (row.direction === 'neutral') {
+    return { name: 'max-regression', status: 'inconclusive', detail: `Metric "${regressionMetric}" measures workload volume, not performance: it has no regression direction to check.` };
+  }
+  if (row.direction !== 'regression') {
+    return { name: 'max-regression', status: 'pass', detail: `Metric "${regressionMetric}" did not regress (${row.direction}).` };
+  }
+  const pct = row.baseline === 0 ? Infinity : Math.abs(row.delta / row.baseline) * 100;
+  const pctLabel = row.baseline === 0
+    ? `regressed from 0 to ${row.delta} (was absent/zero in baseline)`
+    : `regressed ${pct.toFixed(1)}%`;
+  return pct > maxRegressionPct
+    ? { name: 'max-regression', status: 'violation', detail: `Metric "${regressionMetric}" ${pctLabel}, exceeding budget ${maxRegressionPct}%.` }
+    : { name: 'max-regression', status: 'pass', detail: `Metric "${regressionMetric}" ${pctLabel}, within budget ${maxRegressionPct}%.` };
+}
+
+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(', ')}).` };
+  }
+  const matches = band === 'all'
+    ? comparison.findings.introduced
+    : comparison.findings.introduced.filter((f) => f.impactBand === band);
+  return matches.length > 0
+    ? { name: 'fail-on-introduced', status: 'violation', detail: `${matches.length} introduced finding(s) match "${band}".` }
+    : { name: 'fail-on-introduced', status: 'pass', detail: `No introduced findings match "${band}".` };
+}
+
+// Shared by both comparison-dependent budgets below: each needs the same
+// "no comparison yet -> inconclusive" fallback instead of actually checking.
+function pushComparisonBudget(
+  results                ,
+  comparison                               ,
+  name                      ,
+  check                                                 ,
+)       {
+  results.push(comparison ? check(comparison) : { name, status: 'inconclusive', detail: 'No baseline comparison available to evaluate this budget.' });
+}
+
+export function evaluateBudgets({ appModel, catalog, budgets, comparison }   
+                                                                                                 
+ )                                                                        {
+  const results                 = [];
+  if (Number.isFinite(budgets.maxRuntimeMs)) results.push(checkRuntime(appModel, budgets.maxRuntimeMs ));
+  if (Number.isFinite(budgets.maxSpillGb)) results.push(checkSpill(appModel, catalog, budgets.maxSpillGb ));
+  if (Number.isFinite(budgets.maxSkewRatio)) results.push(checkSkew(appModel, budgets.maxSkewRatio ));
+  if (Number.isFinite(budgets.maxFailedTaskRatePct)) results.push(checkFailedTaskRate(appModel, catalog, budgets.maxFailedTaskRatePct ));
+  if (Number.isFinite(budgets.minEfficiencyPct)) results.push(checkEfficiency(appModel, budgets.minEfficiencyPct ));
+  // Guarded here (not just at the CLI/mcp-tools call sites) so any caller of
+  // evaluateBudgets() gets this for free: regressionMetric with no
+  // maxRegressionPct would otherwise skip the whole `if` below silently,
+  // reporting nothing at all instead of a visible inconclusive result.
+  if (budgets.regressionMetric !== undefined && budgets.maxRegressionPct === undefined) {
+    results.push({ name: 'max-regression', status: 'inconclusive', detail: `regressionMetric "${budgets.regressionMetric}" was set without maxRegressionPct; the regression budget was not evaluated.` });
+  } else if (budgets.maxRegressionPct !== undefined) {
+    // `!== undefined`, not `Number.isFinite`: a zero-baseline regression's pct
+    // is itself `Infinity` (see checkRegression), so an "unlimited" budget is a
+    // legitimate finite-typed-as-number input here (CLI's own flag validation
+    // already rejects non-finite --max-regression-pct input, so this only
+    // widens what a direct evaluateBudgets caller, e.g. a test, can express).
+    pushComparisonBudget(results, comparison, 'max-regression',
+      (c) => checkRegression(c, budgets.maxRegressionPct , budgets.regressionMetric ?? 'wallClock'));
+  }
+  if (budgets.failOnIntroduced !== undefined) {
+    pushComparisonBudget(results, comparison, 'fail-on-introduced',
+      (c) => checkFailOnIntroduced(c, budgets.failOnIntroduced ));
+  }
+  return {
+    results,
+    violated: results.some((r) => r.status === 'violation'),
+    inconclusive: results.some((r) => r.status === 'inconclusive'),
+  };
+}

package/vendor-core/cli/collect-run.js

@@ -0,0 +1,107 @@
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { createState, runParse, runParseFiles, reassembleRollingEntries } from '../parser-worker.js';
+import { createModelCallbacks } from '../model-assembler.js';
+import { routeMessage,                     } from '../ingest.js';
+                                            
+
+                           
+                             
+                                                                             
+                                      
+ 
+
+export function emptyAppModel()           {
+  return {
+    app: null,
+    stages: new Map(),
+    executors: { added: [], removed: [] },
+    sql: new Map(),
+    jobs: new Map(),
+    runAggregates: null,
+    evidenceAvailability: null,
+  };
+}
+
+// Mirrors tests/parser-worker.test.js's fakeFile: the proven File-like shape
+// runParse/runParseFiles need (name, size, slice().arrayBuffer(), arrayBuffer()).
+export function nodeFileFromPath(path        )           {
+  const bytes = readFileSync(path);
+  const u8 = new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  return {
+    name: basename(path),
+    size: u8.length,
+    slice(start        , end        ) {
+      const view = u8.subarray(start, end);
+      return { async arrayBuffer() { return view.slice().buffer; } };
+    },
+    async arrayBuffer() { return u8.slice().buffer; },
+  };
+}
+
+// Delegates to src/ingest.js's routeMessage: the single source of truth for
+// worker-message-type -> handler-callback wiring, shared by the browser
+// Worker context and this synchronous-in-Node CLI path. No pendingTaskRequests
+// map: the CLI never sends a 'getTaskData' request, so it never receives a
+// 'taskData' message back.
+export function dispatch(msg         , handlers                )       {
+  routeMessage(msg                                          , handlers);
+}
+
+function isRollingLogDirectory(dirPath        )          {
+  const names = readdirSync(dirPath);
+  return names.some((n        ) => /^events_\d+_/.test(n));
+}
+
+// Shared ingest scaffold for both consumers of routeMessage's onDone/onError
+// dispatch pattern (this file's collectRun, over a local file/dir, and
+// shs-load.ts's collectShsAppModel, over fetched archive bytes): builds a
+// fresh AppModel wired to the shared handlers, then hands `run` a
+// (state, emit, reject) triple so each caller only supplies its own decode
+// step (and its own error type via `onDecodeError` — a plain Error here, an
+// mcpError over in shs-load.ts).
+export function collectViaDispatch(
+  run                                                                                                                   ,
+  onDecodeError                         ,
+)                                                        {
+  const appModel = emptyAppModel();
+  const cb = createModelCallbacks(appModel, { onProgress() {}, onDone() {}, onError() {} });
+
+  return new Promise((resolve, reject) => {
+    const handlers                 = {
+      ...cb,
+      onDone: (msg         ) => resolve({ appModel, skippedLines: (msg                             )?.skippedLines ?? 0 }),
+      onError: (msg         ) => reject(onDecodeError(msg)),
+    };
+    const emit = (msg         ) => dispatch(msg, handlers);
+    const state = createState();
+    run(state, emit, reject);
+  });
+}
+
+export async function collectRun(inputPath        )                                                        {
+  const stat = statSync(inputPath);
+  return collectViaDispatch((state, emit, reject) => {
+    if (stat.isDirectory()) {
+      if (!isRollingLogDirectory(inputPath)) {
+        reject(new Error("This isn't a Spark rolling event-log directory. Pass a single event-log file instead."));
+        return;
+      }
+      const names = readdirSync(inputPath);
+      let ordered;
+      try {
+        ordered = reassembleRollingEntries(names);
+      } catch (e) {
+        reject(e);
+        return;
+      }
+      const files = ordered.map((name) => nodeFileFromPath(join(inputPath, name)));
+      // .catch(reject), not void: an unexpected throw past the parser's own
+      // guards (e.g. in decoder.flush) would otherwise leave this Promise
+      // pending forever and surface only as an unhandled rejection.
+      runParseFiles(files, state, { emit }).catch(reject);
+    } else {
+      runParse(nodeFileFromPath(inputPath), state, { emit }).catch(reject);
+    }
+  }, (msg) => new Error((msg                       ).message));
+}

package/vendor-core/core-count.js

@@ -0,0 +1,68 @@
+// Total cores computation: sum real executor totalCores, or fallback to
+// peakExecutors × configured cores. Used by efficiency model, scaling simulator,
+// wasted core-hours calculation, and utilization/memory-utilization detectors.
+export function computeTotalCores(app                                             , executorsAdded                              )         {
+  let total = executorsAdded.reduce((s, e) => s + (e.totalCores ?? 0), 0);
+  if (total <= 0) {
+    const cores = app.resources?.executor?.cores ?? null;
+    total = cores != null ? executorsAdded.length * cores : 0;
+  }
+  return total;
+}
+
+// Peak concurrently-alive core count: sweeps add/remove events by timestamp
+// (add contributes +totalCores at its own executorId, remove contributes
+// -totalCores looked up from that same executorId) and tracks the running
+// total's max, rather than summing every addition regardless of overlap.
+// computeTotalCores's cumulative sum overstates capacity under dynamic
+// allocation/executor replacement, since a churned-through executor's cores
+// are never actually concurrent with its replacement's; this is the
+// concurrency-aware sibling used to bound the impact estimator's ceiling
+// (src/occupancy.ts's computeCeiling) against that inflation.
+// Tie-break same-timestamp events by delta ascending, so a removal is applied
+// before a same-instant replacement's addition: without this, a seamless swap
+// (old executor gone exactly when its replacement joins) would momentarily
+// double-count both as concurrent.
+function sweepPeak(events                                      )         {
+  const sorted = [...events].sort((a, b) => a.time - b.time || a.delta - b.delta);
+  let running = 0;
+  let peak = 0;
+  for (const ev of sorted) {
+    running += ev.delta;
+    if (running > peak) peak = running;
+  }
+  return peak;
+}
+
+export function computePeakConcurrentCores(
+  app                                             ,
+  executorsAdded                                                                     ,
+  executorsRemoved                                                ,
+)         {
+  const coresByExecutor = new Map                ();
+  const coreEvents                                       = [];
+  const countEvents                                       = [];
+  for (const e of executorsAdded) {
+    const cores = e.totalCores ?? 0;
+    coresByExecutor.set(e.executorId, cores);
+    coreEvents.push({ time: e.timestamp, delta: cores });
+    countEvents.push({ time: e.timestamp, delta: 1 });
+  }
+  for (const e of executorsRemoved) {
+    const cores = coresByExecutor.get(e.executorId) ?? 0;
+    coreEvents.push({ time: e.timestamp, delta: -cores });
+    countEvents.push({ time: e.timestamp, delta: -1 });
+  }
+  const peak = sweepPeak(coreEvents);
+  if (peak > 0) return peak;
+  // Real totalCores data is missing/zero for every add event, so the cores
+  // sweep above can't tell us anything. Falling back to
+  // `executorsAdded.length * cores` here would reintroduce the exact
+  // cumulative-historical-additions overcount this function exists to avoid
+  // (a churned-through executor and its replacement both counted, even
+  // though they were never alive at once). Sweep peak *executor count*
+  // instead: still concurrency-aware, just cores-blind.
+  const peakExecutorCount = sweepPeak(countEvents);
+  const cores = app.resources?.executor?.cores ?? null;
+  return cores != null ? peakExecutorCount * cores : 0;
+}

package/vendor-core/core-locality-ratio.js

@@ -0,0 +1,54 @@
+// Whole-run core-usage-locality ratio: non-local task share across every
+// stage's `stage.localityStats`. Mirrors wasted-core-hours.js's shape (pure
+// reducer, no detector or view coupling), importable by both the
+// `coreLocality` detector (src/detectors.js) and CoreUsageArea.tsx's
+// stage-breakdown list.
+//
+// Locality classification (Spark, best to worst): PROCESS_LOCAL > NODE_LOCAL
+// > NO_PREF > RACK_LOCAL > ANY. NO_PREF is not a locality failure; it's what
+// shuffle-read stages report because there's no location-preference concept
+// for a shuffle fetch, so it stays in the denominator (diluting the ratio for
+// shuffle-heavy stages, which is correct) but never in the numerator.
+const NON_LOCAL_TIERS = new Set(['RACK_LOCAL', 'ANY']);
+const TOP_N = 5;
+const MIN_TASKS_PER_STAGE = 10;
+
+const EMPTY = { totalTasks: null, nonLocalTasks: null, ratio: null, topStages: [] };
+
+export function computeCoreLocalityRatio(stages                                                                          , { minTasksPerStage = MIN_TASKS_PER_STAGE, topN = TOP_N }                                             = {})                                                                                                                                                                          {
+  if (!Array.isArray(stages) || stages.length === 0) return EMPTY;
+
+  let totalTasks = 0;
+  let nonLocalTasks = 0;
+  const perStage = [];
+
+  for (const stage of stages) {
+    const localityStats = stage?.localityStats;
+    if (!Array.isArray(localityStats) || localityStats.length === 0) continue;
+
+    let stageTotal = 0;
+    let stageNonLocal = 0;
+    for (const { locality, count } of localityStats) {
+      if (!Number.isFinite(count)) continue;
+      stageTotal += count;
+      if (NON_LOCAL_TIERS.has(locality)) stageNonLocal += count;
+    }
+    totalTasks += stageTotal;
+    nonLocalTasks += stageNonLocal;
+
+    if (stageTotal >= minTasksPerStage) {
+      perStage.push({
+        stageId: stage.id,
+        nonLocalTasks: stageNonLocal,
+        taskCount: stageTotal,
+        ratio: stageNonLocal / stageTotal,
+      });
+    }
+  }
+
+  if (totalTasks === 0) return EMPTY;
+
+  const topStages = perStage.sort((a, b) => b.nonLocalTasks - a.nonLocalTasks).slice(0, topN);
+
+  return { totalTasks, nonLocalTasks, ratio: nonLocalTasks / totalTasks, topStages };
+}

package/vendor-core/core-time-series.js

@@ -0,0 +1,92 @@
+// Sweep-line "busy cores over time" computation. Pure and side-effect-free so
+// it can run inside parser-worker.js (over retained task launch/finish
+// timestamps) or on the main thread (scaling simulator). One core per task:
+// Spark's default task-to-core mapping.
+//
+// `hypotheticalCores` clamps the concurrent busy-core count to N (the
+// deterministic "utilization at N cores" curve). It does NOT re-schedule tasks;
+// makespan re-estimation is the scaling simulator's job, layered on this signal.
+
+                    
+                 
+                 
+ 
+
+                   
+                 
+               
+               
+ 
+
+function buildStepFunction(intervals            , hypotheticalCores               )            {
+  // Emit +1 at launch, -1 at finish. Skip empty/negative intervals.
+  const events                                      = [];
+  for (const { launch, finish } of intervals) {
+    if (!(finish > launch)) continue;
+    events.push({ t: launch, delta: 1 });
+    events.push({ t: finish, delta: -1 });
+  }
+  // Sort by time; at equal time process -1 before +1 so [launch, finish) is
+  // half-open (a task finishing exactly as another launches does not overlap).
+  events.sort((a, b) => (a.t - b.t) || (a.delta - b.delta));
+
+  // Walk consecutive timestamps, emitting the busy level held on each interval.
+  const segments            = [];
+  let busy = 0;
+  for (let i = 0; i < events.length; i++) {
+    const cur = events[i];
+    busy += cur.delta;
+    const next = events[i + 1];
+    if (!next || next.t === cur.t) continue;
+    const effective = hypotheticalCores != null ? Math.min(busy, hypotheticalCores) : busy;
+    segments.push({ tStart: cur.t, tEnd: next.t, busy: effective });
+  }
+  return segments;
+}
+
+export function computeCoreTimeSeries(intervals            , {
+  bucketBy = 'time',
+  bucketWidthMs = 1000,
+  hypotheticalCores = null,
+}   
+                                  
+                         
+                                    
+  = {})                                                
+               
+                        
+                           
+                         
+                                                                                             
+  {
+  const segments = buildStepFunction(intervals, hypotheticalCores);
+
+  if (bucketBy === 'coreCount') {
+    const histogram           = [];
+    for (const seg of segments) {
+      histogram[seg.busy] = (histogram[seg.busy] ?? 0) + (seg.tEnd - seg.tStart);
+    }
+    // Fill sparse holes with 0 so the array reads as a dense histogram.
+    for (let k = 0; k < histogram.length; k++) if (histogram[k] === undefined) histogram[k] = 0;
+    return { mode: 'coreCount', histogram };
+  }
+
+  // bucketBy === 'time'
+  if (segments.length === 0) {
+    return { mode: 'time', bucketWidthMs, startTime: null, endTime: null, buckets: [] };
+  }
+  const startTime = segments[0].tStart;
+  const endTime = segments[segments.length - 1].tEnd;
+  const buckets                                                                                    = [];
+  for (let tStart = startTime; tStart < endTime; tStart += bucketWidthMs) {
+    const tEnd = tStart + bucketWidthMs;
+    let busyCoreMs = 0;
+    for (const seg of segments) {
+      const lo = Math.max(seg.tStart, tStart);
+      const hi = Math.min(seg.tEnd, tEnd);
+      if (hi > lo) busyCoreMs += seg.busy * (hi - lo);
+    }
+    buckets.push({ tStart, tEnd, busyCoreMs, avgBusyCores: busyCoreMs / bucketWidthMs });
+  }
+  return { mode: 'time', bucketWidthMs, startTime, endTime, buckets };
+}

package/vendor-core/core-usage-locality.js

@@ -0,0 +1,70 @@
+// Stage-granular approximation of core-usage-by-locality over time. See the
+// plan's Task 6 DEVIATION note: per-task locality is not retained, so this
+// distributes each stage's executorRunTime across its wall-clock window,
+// split by localityStats proportions. Not exact; approximate by construction.
+export const LOCALITY_TIERS           = ['PROCESS_LOCAL', 'NODE_LOCAL', 'RACK_LOCAL', 'NO_PREF', 'ANY'];
+
+                         
+                       
+                       
+                           
+                                                        
+ 
+
+                                     
+                         
+                   
+ 
+
+                                    
+                   
+                                   
+ 
+
+export function computeLocalityAreaSeries(
+  stages                 ,
+  { bucketWidthMs = 60_000, tiers = LOCALITY_TIERS }                            = {},
+)                           {
+  const valid = stages.filter(s => (s.completedAt ?? 0) > (s.submittedAt ?? 0) && (s.executorRunTime ?? 0) > 0);
+  if (valid.length === 0) return { labels: [], series: {} };
+  const startTime = valid.reduce((m, s) => Math.min(m, s.submittedAt ?? m), Infinity);
+  const endTime = valid.reduce((m, s) => Math.max(m, s.completedAt ?? m), -Infinity);
+  const nBuckets = Math.max(1, Math.ceil((endTime - startTime) / bucketWidthMs));
+
+  const series                           = {};
+  for (const tier of tiers) series[tier] = new Array(nBuckets).fill(0);
+  const other = new Array(nBuckets).fill(0); // localities not in the fixed tier list
+
+  for (const s of valid) {
+    const completedAt = s.completedAt ?? 0;
+    const submittedAt = s.submittedAt ?? 0;
+    const wall = completedAt - submittedAt;
+    const avgCores = (s.executorRunTime ?? 0) / wall; // core-time / wall-time = avg concurrent cores
+    const total = (s.localityStats ?? []).reduce((a, l) => a + l.count, 0) || 1;
+    const props = new Map((s.localityStats ?? []).map(l => [l.locality, l.count / total]));
+    // spread avgCores over the buckets this stage overlaps, weighted by overlap fraction
+    for (let b = 0; b < nBuckets; b++) {
+      const bStart = startTime + b * bucketWidthMs;
+      const bEnd = bStart + bucketWidthMs;
+      const overlap = Math.min(completedAt, bEnd) - Math.max(submittedAt, bStart);
+      if (overlap <= 0) continue;
+      const frac = overlap / bucketWidthMs; // portion of the bucket this stage covers
+      for (const [loc, p] of props) {
+        const add = avgCores * p * frac;
+        if (series[loc]) series[loc][b] += add;
+        else other[b] += add;
+      }
+    }
+  }
+  if (other.some(v => v > 0)) series.OTHER = other;
+
+  // idle = peak total busy across buckets, minus each bucket's total busy.
+  const totals = new Array(nBuckets).fill(0);
+  for (const tier of Object.keys(series)) for (let b = 0; b < nBuckets; b++) totals[b] += series[tier][b];
+  const peak = totals.reduce((m, v) => Math.max(m, v), 0);
+  series.idle = totals.map(v => Math.max(0, peak - v));
+
+  const labels           = [];
+  for (let b = 0; b < nBuckets; b++) labels.push(startTime + b * bucketWidthMs);
+  return { labels, series };
+}