sparkforensics-cli 0.1.0

package/vendor-core/run-comparison.js

@@ -0,0 +1,458 @@
+// src/run-comparison.ts
+import { computeWallClock } from './wall-clock.js';
+import { normalizeDetail } from './detectors.js';
+import { captureSnapshot } from './session-snapshot.js';
+                                                                                   
+                                                             
+
+                                 
+                             
+                                                                          
+                                                                                    
+                             
+ 
+                                   
+                                                                                                          
+ 
+                                    
+                                                
+                                                  
+                          
+                            
+                                                                             
+                                                                                                                  
+                                                                            
+                                                                            
+ 
+
+// Replace run-varying tokens (digit runs, long hex ids) with a stable marker so
+// the same logical stage across two runs normalizes to one identity.
+export function normalizeStageName(name        )         {
+  return String(name)
+    .toLowerCase()
+    .replace(/\b[0-9a-f]{8,}\b/g, '#') // hex ids/uuids first (they contain digits)
+    .replace(/\d+/g, '#')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+// cyrb53: fast, non-cryptographic 53-bit string hash, deterministic, portable
+// (runs in-browser worker and Node CLI, no crypto module dependency), fixed-
+// length hex output regardless of input size. src/analyzer.js already has a
+// small stable-hash helper (`fnv1a`, 32-bit) for deterministic finding ids,
+// but that runs once per finding; planTreeIdentity's `visit` below runs once
+// per PLAN NODE, for every stage, in both runs of a comparison: orders of
+// magnitude more hash calls, so the smaller 32-bit space's birthday-collision
+// risk is a real concern here in a way it isn't for finding ids. 53 bits keeps
+// collision probability negligible at that scale; adequate for a same-run
+// identity key, not a security boundary.
+function cyrb53(str        , seed = 0)         {
+  let h1 = 0xdeadbeef ^ seed, h2 = 0x41c6ce57 ^ seed;
+  for (let i = 0; i < str.length; i++) {
+    const ch = str.charCodeAt(i);
+    h1 = Math.imul(h1 ^ ch, 2654435761);
+    h2 = Math.imul(h2 ^ ch, 1597334677);
+  }
+  h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^ Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+  h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^ Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+  return (4294967296 * (2097151 & h2) + (h1 >>> 0)).toString(16);
+}
+
+// Bottom-up, order-independent structural identity of a resolved plan tree:
+// each node folds its own normalized name and normalized `detail` with its
+// already-computed children's DIGESTS (children sorted, so sibling
+// reordering across runs (e.g. AQE picking a different broadcast side)
+// still matches), so two plans collide only when their whole shape AND every
+// node's normalized detail agree. `normalizeDetail` (src/detectors.js, built
+// for cachingOpportunity's composite join/union detection) strips expr ids,
+// `plan_id=`, codegen-stage numbers, and AQE's BuildLeft/BuildRight choice,
+// and canonicalizes commutative equality operands: exactly the run-to-run
+// noise a cross-run identity needs to ignore. Replaces the previous
+// flatten-and-sort-names identity, which ignored `detail` entirely (so a
+// join on one column and a join on another, with identical operator names,
+// collided) and ignored nesting (so two differently-shaped trees sharing a
+// node-name multiset also collided).
+//
+// Each node is encoded via JSON.stringify of its [name, detail, childDigests]
+// triple rather than an ad hoc delimiter-joined string: real Spark `detail`
+// text routinely contains its own `<`/`>`/`{`/`}`/`,` characters (e.g.
+// `ReadSchema: struct<id:bigint>`), so a hand-rolled delimiter scheme could
+// let two structurally different plans serialize to the same string;
+// JSON.stringify escapes/quotes each component so the encoding is
+// unambiguous. Critically, that JSON payload is then folded down to a fixed-
+// length `cyrb53` digest before being returned: the payload only ever
+// contains a node's own (short) name/detail plus an array of already-hashed,
+// fixed-length child digests, never a raw nested JSON blob. Embedding full
+// child identity STRINGS instead (this function's first version) made each
+// level re-stringify-and-escape the level below, so identity length grew
+// ~2^depth; real Spark plans routinely nest 20-60+ operators deep
+// (Scan→Filter→Project→HashAggregate→Exchange→Sort→Join, repeated per
+// join/aggregate), which blew up to megabytes-per-stage or a
+// `RangeError: Invalid string length` well within that range. Digest-folding
+// keeps per-node output size bounded by name+detail length plus a small
+// constant per child, independent of subtree depth.
+function planTreeIdentity(root                             )                {
+  if (!root) return null;
+  function visit(node          )         {
+    const childDigests = (node.children ?? []).map(visit).sort();
+    return cyrb53(JSON.stringify([normalizeStageName(node.name ?? ''), normalizeDetail(node.detail ?? ''), childDigests]));
+  }
+  return visit(root);
+}
+
+// Plan identity for the stage's SQL execution, so stage identity also requires
+// the SQL-node identity to agree. Empty string when no SQL/plan.
+function sqlNodeIdentity(stage       , snapshot                 )         {
+  const execId = stage.sqlExecutionId;
+  if (execId == null) return '';
+  return planTreeIdentity(snapshot.sql.get(execId)?.planTree ?? null) ?? '';
+}
+
+export function stageIdentity(stage       , snapshot                 )         {
+  return normalizeStageName(stage.name ?? '') + '§' + sqlNodeIdentity(stage, snapshot);
+}
+
+function identityIndex(snapshot                 )                        {
+  const byIdentity = new Map                  (); // identity -> stageId[]
+  for (const [id, stage] of snapshot.stages) {
+    const key = stageIdentity(stage, snapshot);
+    const ids = byIdentity.get(key);
+    if (ids) ids.push(id);
+    else byIdentity.set(key, [id]);
+  }
+  return byIdentity;
+}
+
+export function matchStages(baseSnap                 , candSnap                 )   
+                                                                     
+                                 
+                                   
+                   
+  {
+  const baseIdx = identityIndex(baseSnap);
+  const candIdx = identityIndex(candSnap);
+  const pairs                                                              = [];
+  const matchedIdentities = new Set        ();
+  const collisionIdentities = new Set        ();
+  // A collision is a single-run property: any identity that more than one stage
+  // in the SAME run normalizes to. Record them per-run, independent of whether
+  // the other run shares that identity (a colliding stage with no counterpart
+  // still makes the run ambiguous).
+  for (const idx of [baseIdx, candIdx])
+    for (const [identity, ids] of idx) if (ids.length > 1) collisionIdentities.add(identity);
+  // Pair only identities that map to exactly one stage on BOTH sides.
+  // Deterministic order: sort identities lexically.
+  for (const identity of [...baseIdx.keys()].sort()) {
+    if (!candIdx.has(identity)) continue;
+    const baseIds = baseIdx.get(identity) ;
+    const candIds = candIdx.get(identity) ;
+    if (baseIds.length > 1 || candIds.length > 1) continue; // collision already recorded above
+    pairs.push({ identity, baseId: baseIds[0], candId: candIds[0] });
+    matchedIdentities.add(identity);
+  }
+  const total = baseSnap.stages.size + candSnap.stages.size;
+  const coverage = total === 0 ? 0 : (2 * pairs.length) / total;
+  return { pairs, matchedIdentities, collisionIdentities, coverage };
+}
+
+function p95(values          )                {
+  if (values.length === 0) return null;
+  const sorted = [...values].sort((a, b) => a - b);
+  const rank = Math.ceil(0.95 * sorted.length) - 1; // nearest-rank, deterministic
+  return sorted[Math.min(sorted.length - 1, Math.max(0, rank))];
+}
+
+// The stage numeric fields sumField/perStageMetrics read; keeps the generic
+// `field` parameter narrowed to a known numeric Stage property instead of
+// widening to `string` (Stage also carries a `[key: string]: unknown` index
+// signature for detector-only fields).
+                        
+                                                                          
+                                                                    
+
+// Sum a numeric stage field over a stage list; `present` is false when no stage
+// carried a finite value (so the metric renders Unavailable rather than a false 0).
+function sumField(stages         , field                   )                                    {
+  let sum = 0, present = false;
+  for (const s of stages) {
+    const v = s[field];
+    if (Number.isFinite(v)) { sum += v          ; present = true; }
+  }
+  return { sum, present };
+}
+
+// Shared by skewRatios (whole-run p95 input) and stageSkewDeltas' `ratio`
+// closure (per-pair matched comparison): both need the identical per-stage
+// task-skew formula (max task duration over stage wall-clock duration).
+function stageSkewRatio(stage       )                {
+  const dur = (stage.completedAt ?? 0) - (stage.submittedAt ?? 0);
+  return dur > 0 && Number.isFinite(stage.taskDurationMax) ? (stage.taskDurationMax          ) / dur : null;
+}
+
+function skewRatios(stages         )           {
+  const out           = [];
+  for (const s of stages) {
+    const ratio = stageSkewRatio(s);
+    if (ratio != null) out.push(ratio);
+  }
+  return out;
+}
+
+// Volume/count metrics, not cost metrics: more or less input/output data, or
+// tasks/executors, isn't inherently better or worse (it may just reflect a
+// differently-sized job), unlike wall-clock, spill, GC, etc. Exported as the
+// single source of truth for "which metrics have no better/worse direction",
+// shared by the view (RunComparison.tsx, for Δ coloring) and by
+// src/cli/budgets.ts's checkRegression (so a `--regression-metric inputBytes`
+// budget can't misread "processed more data" as a regression).
+export const NEUTRAL_METRIC_KEYS                      = new Set(['inputBytes', 'outputBytes', 'taskCount', 'executorsAdded']);
+
+function direction(key        , baseline               , candidate               )                              {
+  if (baseline == null || candidate == null) return 'unavailable';
+  if (NEUTRAL_METRIC_KEYS.has(key)) return candidate === baseline ? 'unchanged' : 'neutral';
+  const d = candidate - baseline;
+  return d < 0 ? 'improvement' : d > 0 ? 'regression' : 'unchanged';
+}
+
+function metric(
+  key        , label        , baseline               , candidate               ,
+  extra                                 = {},
+)                 {
+  const dir = direction(key, baseline, candidate);
+  const delta = baseline == null || candidate == null ? null : candidate - baseline;
+  return { key, label, baseline, candidate, delta, direction: dir, ...extra };
+}
+
+export function metricDeltas(baseSnap                 , candSnap                 )                   {
+  const out                   = [];
+
+  // Wall-clock: always computable (computeWallClock tolerates a null app).
+  out.push(metric('wallClock', 'Wall-clock duration',
+    computeWallClock(baseSnap.app, baseSnap.stages).total,
+    computeWallClock(candSnap.app, candSnap.stages).total));
+
+  // Shuffle spill over the whole run: a sum needs no stage matching, and
+  // matching is unreliable on real logs (see plan rationale), so scope it to
+  // all stages exactly like task-skew and failed-rate below.
+  const bSpill = sumField([...baseSnap.stages.values()], 'memoryBytesSpilled');
+  const cSpill = sumField([...candSnap.stages.values()], 'memoryBytesSpilled');
+  out.push(metric('shuffleSpill', 'Shuffle spill',
+    bSpill.present ? bSpill.sum : null, cSpill.present ? cSpill.sum : null,
+    { unavailableReason: bSpill.present && cSpill.present ? undefined : 'No shuffle-spill data recorded for a run' }));
+
+  // Task skew: p95 of per-stage ratio across the whole run.
+  const bSkew = p95(skewRatios([...baseSnap.stages.values()]));
+  const cSkew = p95(skewRatios([...candSnap.stages.values()]));
+  out.push(metric('taskSkew', 'Task skew (p95)', bSkew, cSkew,
+    { unavailableReason: bSkew != null && cSkew != null ? undefined : 'No stage had measurable duration for a run' }));
+
+  // Failed-task rate: Σ failedTasks / Σ taskCount.
+  const bTasks = sumField([...baseSnap.stages.values()], 'taskCount');
+  const cTasks = sumField([...candSnap.stages.values()], 'taskCount');
+  const bFailed = sumField([...baseSnap.stages.values()], 'failedTasks');
+  const cFailed = sumField([...candSnap.stages.values()], 'failedTasks');
+  // Guard on BOTH inputs: a missing `failedTasks` field must render Unavailable,
+  // not a false 0% rate (dividing an absent-and-therefore-0 numerator).
+  const bRate = bTasks.present && bTasks.sum > 0 && bFailed.present ? bFailed.sum / bTasks.sum : null;
+  const cRate = cTasks.present && cTasks.sum > 0 && cFailed.present ? cFailed.sum / cTasks.sum : null;
+  out.push(metric('failedTaskRate', 'Failed-task rate', bRate, cRate,
+    { unavailableReason: bRate != null && cRate != null ? undefined : 'No task or failure counts recorded for a run' }));
+
+  // Additional whole-run aggregates: plain sums of fields the stage already
+  // carries (set in finalizeStage). Correct at any match coverage, like the
+  // sums above; no parser or detector change.
+  const sumMetric = (key        , label        , field                   , reason        ) => {
+    const b = sumField([...baseSnap.stages.values()], field);
+    const c = sumField([...candSnap.stages.values()], field);
+    out.push(metric(key, label, b.present ? b.sum : null, c.present ? c.sum : null,
+      { unavailableReason: b.present && c.present ? undefined : reason }));
+  };
+  sumMetric('diskSpill', 'Disk spill', 'diskBytesSpilled', 'No disk-spill data recorded for a run');
+  sumMetric('gcTime', 'GC time', 'jvmGCTime', 'No GC-time data recorded for a run');
+  sumMetric('inputBytes', 'Input read', 'inputBytes', 'No input-bytes data recorded for a run');
+  sumMetric('outputBytes', 'Output written', 'outputBytes', 'No output-bytes data recorded for a run');
+  sumMetric('executorRunTime', 'Executor run-time', 'executorRunTime', 'No executor run-time recorded for a run');
+  sumMetric('taskCount', 'Task count', 'taskCount', 'No task counts recorded for a run');
+
+  // Executor count is app-level, not per-stage. `executors` is absent on
+  // hand-built snapshots; guard so it renders Unavailable, not a crash.
+  const execCount = (snap                 )                =>
+    (Array.isArray(snap.executors?.added) ? snap.executors.added.length : null);
+  const bExec = execCount(baseSnap), cExec = execCount(candSnap);
+  out.push(metric('executorsAdded', 'Executors added', bExec, cExec,
+    { unavailableReason: bExec != null && cExec != null ? undefined : 'No executor events recorded for a run' }));
+
+  return out;
+}
+
+// Finding categories are counted, not matched: a (rule × impact band) tally needs
+// no cross-run stage identity, so it stays correct even when almost no stages
+// match uniquely (the common case on real logs, see plan rationale). A
+// category the candidate has more of is "introduced"; fewer, "resolved".
+export function findingsDelta(baseSnap                 , candSnap                 )   
+                                                               
+  {
+                                                                                                
+  const tally = (snap                 )                          => {
+    const m = new Map                    (); // `${rule}§${impactBand}` -> { rule, impactBand, count, stages:Set }
+    for (const f of snap.catalog) {
+      const rule = typeof f.rule === 'string' ? f.rule : f.type;
+      const impactBand = f.impactBand ?? 'unknown';
+      const key = `${rule}§${impactBand}`;
+      const e = m.get(key) ?? { rule, impactBand, count: 0, stages: new Set        () };
+      e.count++;
+      // Resolve stageId → name on this snapshot only: a single-side lookup, so
+      // it needs no cross-run identity. App-level findings (stageId null) add none.
+      const stage = f.stageId != null ? snap.stages.get(f.stageId) : null;
+      if (stage?.name) e.stages.add(stage.name);
+      m.set(key, e);
+    }
+    return m;
+  };
+  const b = tally(baseSnap), c = tally(candSnap);
+  const introduced                     = [], resolved                     = [];
+  for (const key of [...new Set([...b.keys(), ...c.keys()])].sort()) {
+    const be = b.get(key), ce = c.get(key);
+    const baseCount = be?.count ?? 0;
+    const candCount = ce?.count ?? 0;
+    if (candCount === baseCount) continue;
+    const meta = ce ?? be ;
+    const more = candCount > baseCount ? ce  : be ; // the side with more supplies the labels
+    const row                   = { rule: meta.rule, impactBand: meta.impactBand, baseCount, candCount,
+      delta: candCount - baseCount, stages: [...more.stages].sort() };
+    (candCount > baseCount ? introduced : resolved).push(row);
+  }
+  return { introduced, resolved };
+}
+
+function namesConflict(a                     , b                     )          {
+  return a?.name != null && b?.name != null && a.name !== b.name;
+}
+
+// A pair's skew ratio is null when the stage's duration wasn't measurable
+// (see `ratio` below), matching CompareRunsResult['stageSkew']'s nullable
+// baseline/candidate/delta fields.
+function stageSkewDeltas(
+  baseSnap                 ,
+  candSnap                 ,
+  match                                                                        ,
+)                                                                                                       {
+  return match.pairs.map((p) => {
+    const b = stageSkewRatio(baseSnap.stages.get(p.baseId) );
+    const c = stageSkewRatio(candSnap.stages.get(p.candId) );
+    return { identity: p.identity, baseline: b, candidate: c, delta: b != null && c != null ? c - b : null };
+  }).sort((x, y) => x.identity < y.identity ? -1 : x.identity > y.identity ? 1 : 0);
+}
+
+// Compact, view-friendly per-stage record for the manual stage-pinning panel.
+// Every field is number | null; a null means the stage did not carry it.
+// Exported: it's CompareRunsResult['baseStages'/'candStages']'s metrics type.
+                                  
+                          
+                                    
+                                  
+                           
+                            
+                             
+                                 
+                           
+                             
+ 
+
+function perStageMetrics(stage       )                  {
+  const num = (v         )                => (Number.isFinite(v) ? (v          ) : null);
+  const dur = (stage.completedAt ?? 0) - (stage.submittedAt ?? 0);
+  return {
+    duration: dur > 0 ? dur : null,
+    memoryBytesSpilled: num(stage.memoryBytesSpilled),
+    diskBytesSpilled: num(stage.diskBytesSpilled),
+    jvmGCTime: num(stage.jvmGCTime),
+    inputBytes: num(stage.inputBytes),
+    outputBytes: num(stage.outputBytes),
+    executorRunTime: num(stage.executorRunTime),
+    taskCount: num(stage.taskCount),
+    failedTasks: num(stage.failedTasks),
+  };
+}
+
+function stageList(snap                 )                                                                {
+  return [...snap.stages].map(([id, s]) => ({ id, name: s.name ?? `Stage ${id}`, metrics: perStageMetrics(s) }));
+}
+
+// Shared by every buildComparison caller below: captureSnapshot only ever
+// copies this into a fresh Map internally, never mutates the caller's
+// reference, so one shared empty Map is safe in place of a fresh allocation
+// per call.
+const EMPTY_TASK_DATA = new Map                 ();
+
+// Wraps the analyze()-to-compareRuns() snapshot-building sequence shared by
+// the CLI's --baseline path and mcp-tools.ts's compareRuns tool: both need
+// captureSnapshot (with an empty taskDataCache — the interactive drill-down
+// cache, never read by compareRuns/matchStages/metricDeltas/findingsDelta)
+// for each side before diffing them.
+export function buildComparison(
+  baseline                                                           ,
+  candidate                                                           ,
+)                    {
+  return compareRuns(
+    { label: baseline.label, snapshot: captureSnapshot(baseline.appModel, baseline.catalog, EMPTY_TASK_DATA) },
+    { label: candidate.label, snapshot: captureSnapshot(candidate.appModel, candidate.catalog, EMPTY_TASK_DATA) },
+  );
+}
+
+export function compareRuns(
+  baseline                                              ,
+  candidate                                              ,
+)                    {
+  const baseSnap = baseline.snapshot, candSnap = candidate.snapshot;
+  const match = matchStages(baseSnap, candSnap);
+  // Name equality is a weak confidence signal, not a hard gate: renaming a job
+  // is the normal way to label an A/B experiment, so a mismatch must not block
+  // the (matching-free, name-independent) deltas. Surface it as `low` instead.
+  const namesDiffer = namesConflict(baseSnap.app, candSnap.app);
+  return {
+    baselineLabel: baseline.label, candidateLabel: candidate.label,
+    confidence: namesDiffer ? 'low' : 'ok',
+    reason: namesDiffer ? 'Run names differ, so deltas may compare different work.' : null,
+    matchedCoverage: match.coverage,
+    metrics: metricDeltas(baseSnap, candSnap),
+    findings: findingsDelta(baseSnap, candSnap),
+    stageSkew: stageSkewDeltas(baseSnap, candSnap, match),
+    baseStages: stageList(baseSnap),
+    candStages: stageList(candSnap),
+  };
+}
+
+// One introduced/resolved findings-delta block: `### <title> (<count>)`
+// heading followed by one bullet per finding.
+function renderFindingsSection(title        , findings                    )           {
+  const lines = [`### ${title} (${findings.length})`, ''];
+  for (const f of findings) {
+    lines.push(`- [${f.impactBand}] ${f.rule}: ${f.baseCount} -> ${f.candCount}`);
+  }
+  return lines;
+}
+
+// Small Markdown renderer for the comparison section, matching
+// evidence-report.ts's renderMarkdown house style (## section heading, ###
+// subheadings, `- key: value` bullets). Shared by the CLI's --baseline
+// markdown output and the MCP server's compare_runs `format: 'md'`.
+export function renderComparisonMarkdown(comparison                   )         {
+  const lines = ['', '## Comparison to baseline', ''];
+  if (comparison.confidence === 'low') {
+    lines.push(`- confidence: low — ${comparison.reason}`);
+    lines.push('');
+  }
+  lines.push(`- matched stage coverage: ${(comparison.matchedCoverage * 100).toFixed(1)}%`);
+  lines.push('');
+  lines.push('### Metric deltas');
+  lines.push('');
+  for (const m of comparison.metrics) {
+    lines.push(`- ${m.label}: ${m.baseline ?? 'n/a'} -> ${m.candidate ?? 'n/a'} (${m.direction})`);
+  }
+  lines.push('');
+  lines.push(...renderFindingsSection('Introduced findings', comparison.findings.introduced));
+  lines.push('');
+  lines.push(...renderFindingsSection('Resolved findings', comparison.findings.resolved));
+  return lines.join('\n');
+}

package/vendor-core/scaling-sim.js

@@ -0,0 +1,73 @@
+// §4 What-if executor-scaling simulator (SparkLens ExecutorWallclockAnalyzer).
+// DESIGN SPIKE: the makespan model is a first-cut approximation and is NOT
+// validated against ground truth (a single event log only ever observes one
+// scale). Every prediction ships with a Model Error confidence indicator.
+//
+// Builds on computeCoreTimeSeries' clamp conceptually, but operates on the
+// worker-posted per-stage aggregates (runAggregates.perStage) so raw task data
+// never reaches the main thread.
+import { computeWallClock } from './wall-clock.js';
+import { computeTotalCores } from './core-count.js';
+                                                                             
+
+const TEST_PERCENTAGES           = [10, 20, 50, 80, 100, 110, 120, 150, 200, 300, 400, 500];
+
+// Idealized makespan: total task-time spread over min(cores, taskCount) cores.
+export function estimatedStageDurationAtCores(totalTaskDurationSum        , taskCount        , cores        )         {
+  if (taskCount <= 0 || cores <= 0) return 0;
+  return totalTaskDurationSum / Math.min(cores, taskCount);
+}
+
+// Sum estimated per-stage durations at N cores. Idealized: ignores scheduling
+// overhead, locality, shuffle-fetch contention (all captured in the real run's
+// actual duration at current scale, hence Model Error).
+function estimatedTotalAtCores(perStage                                                                     , cores        )         {
+  let sum = 0;
+  for (const stageId of Object.keys(perStage)) {
+    const { totalTaskDurationSum, taskCount } = perStage[stageId];
+    sum += estimatedStageDurationAtCores(totalTaskDurationSum, taskCount, cores);
+  }
+  return sum;
+}
+
+export function simulateScaling({ app, stages, runAggregates, executorsAdded }   
+                           
+                               
+                                      
+                                  
+ )   
+                        
+                            
+                                                                            
+                               
+  {
+  const perStage = runAggregates?.perStage ?? {};
+  // `app ?? {}`: computeTotalCores just falls back to the executor-derived core sum when
+  // `resources` is absent, and every caller here already tolerates a null `app` (malformed
+  // logs with no ApplicationStart); `app!` would crash on `app.resources` in that case.
+  // `executorsAdded` cast: computeTotalCores only reads `totalCores`, present on
+  // ExecutorAddedEvent (the only kind real callers pass here) but not ExecutorRemovedEvent,
+  // so the union as a whole is a structural mismatch against computeTotalCores's
+  // `{totalCores?}` shape.
+  const baselineCores = computeTotalCores(app ?? {}, executorsAdded                                  );
+  const wc = computeWallClock(app, stages                                                               );
+  const observedActiveMs = wc.stagesActive;
+
+  // Model Error: predicted-at-baseline vs. observed stages-active wall-clock.
+  const predictedAtBaseline = baselineCores > 0 ? estimatedTotalAtCores(perStage, baselineCores) : 0;
+  const modelErrorPct = observedActiveMs > 0
+    ? Math.round(Math.abs(predictedAtBaseline - observedActiveMs) / observedActiveMs * 100)
+    : null;
+
+  // Scale factor projects the idealized sum onto the observed active wall-clock,
+  // so predictions are relative to the real run rather than the raw idealization.
+  const scale = predictedAtBaseline > 0 ? observedActiveMs / predictedAtBaseline : 1;
+
+  const predictions = TEST_PERCENTAGES.map(pct => {
+    const cores = Math.max(1, Math.round(baselineCores * pct / 100));
+    const estMakespanMs = Math.round(estimatedTotalAtCores(perStage, cores) * scale);
+    return { pct, cores, estMakespanMs };
+  });
+
+  return { baselineCores, testPercentages: TEST_PERCENTAGES, predictions, modelErrorPct };
+}

package/vendor-core/session-snapshot.js

@@ -0,0 +1,79 @@
+// Lightweight in-memory snapshot of a parsed file's view state, so switching
+// between already-parsed files is instant without keeping multiple workers
+// alive. Holds only the summary AppModel + catalog + prefetched task data,
+// never the worker's full taskStore.
+
+import { isSupportedEvidenceAvailability } from './evidence-availability.js';
+             
+           
+          
+               
+        
+                
+               
+      
+                
+                       
+                    
+
+                                  
+                           
+                             
+                                                                  
+                                 
+                         
+                                      
+                                                    
+                     
+                                 
+ 
+
+export function captureSnapshot(
+  appModel          ,
+  catalog           ,
+  taskDataCache                      ,
+)                  {
+  return {
+    app: appModel.app,
+    stages: new Map(appModel.stages),
+    executors: {
+      added: [...appModel.executors.added],
+      removed: [...appModel.executors.removed],
+    },
+    sql: new Map(appModel.sql),
+    jobs: new Map(appModel.jobs),
+    runAggregates: appModel.runAggregates,
+    evidenceAvailability: appModel.evidenceAvailability,
+    catalog: [...catalog],
+    taskData: new Map(taskDataCache),
+  };
+}
+
+// Restores a snapshot by mutating the live `appModel` and `taskDataCache` in
+// place, so references captured elsewhere (e.g. the stage-detail modal closure)
+// keep pointing at the current data. Returns the restored catalog.
+export function applySnapshot(
+  appModel          ,
+  taskDataCache                      ,
+  snapshot                 ,
+)            {
+  appModel.app = snapshot.app;
+  appModel.stages = new Map(snapshot.stages);
+  appModel.executors = {
+    added: [...snapshot.executors.added]                                  ,
+    removed: [...snapshot.executors.removed]                                    ,
+  };
+  appModel.sql = new Map(snapshot.sql);
+  appModel.jobs = new Map(snapshot.jobs);
+  appModel.runAggregates = snapshot.runAggregates ?? null;
+  // Fail-closed on unknown schema versions: a future incompatible ledger is
+  // never trusted as V1 data (fixes: schemaVersion must be validated at read).
+  appModel.evidenceAvailability = isSupportedEvidenceAvailability(snapshot.evidenceAvailability)
+    ? snapshot.evidenceAvailability
+    : null;
+
+  taskDataCache.clear();
+  for (const [k, v] of snapshot.taskData) taskDataCache.set(k, v);
+
+  return [...snapshot.catalog];
+}