sparkforensics-mcp 0.2.4 → 0.4.0

package/vendor-core/redact.js

@@ -7,7 +7,9 @@
 // Deterministic (sorted assignment), idempotent (pseudonyms map to themselves),
 // and non-mutating (returns a fresh, deep-copied tree).
 
-                                                      
+import { decodeCollections, encodeCollections,                    } from './export-data.js';
+                                                    
+import { redactTaskFailureGroup,                        } from './task-failure.js';
 
 // Host / IP identifier patterns. Used to enumerate host names that surface only
 // inside free text: recommendation strings, `stageFailed`'s failure-reason
@@ -34,7 +36,7 @@ const APP_ID_PATTERNS = [/\bapplication_\d{10,}_\d+\b/g];
 // Walk every string in the tree once, collecting matches for each `{ patterns,
 // out }` sink. One shared traversal for every token kind (instead of one
 // traversal per kind) keeps redactComparison's dual host+app-id scan the same
-// cost as the single-kind scan redactReport/redactAppIdentity already do.
+// cost as the single-kind scan redactReport already does.
 function scanTokens(node         , sinks                                                 )       {
   if (typeof node === 'string') {
     for (const { patterns, out } of sinks) {
@@ -54,11 +56,6 @@ function scanTokens(node         , sinks
   }
 }
 
-// Walk every string in the tree, collecting host/IP tokens into `hosts`.
-function scanHostTokens(node         , hosts             )       {
-  scanTokens(node, [{ patterns: HOST_PATTERNS, out: hosts }]);
-}
-
 // Recursively collects every string value found under a key literally named
 // `host`, anywhere in the tree. Host names surface at several depths, a
 // finding's own `host`, `evidence.host`, and now
@@ -79,12 +76,31 @@ function collectHostFields(node         , hosts             )       {
   }
 }
 
+// A failed-task error's message and stack text can carry file paths and data values that no
+// host/app-id pattern recognizes, so they are dropped rather than pseudonymized: every array under
+// a key named `failureGroups` (a `failures` finding's, or a stage's in the HTML export) gets
+// redactTaskFailureGroup applied. Walking by key name, like collectHostFields, needs no path list.
+// Returns a fresh tree.
+function redactFailureGroups   (node   )    {
+  if (Array.isArray(node)) return node.map((n) => redactFailureGroups(n))     ;
+  if (node && typeof node === 'object') {
+    const out                          = {};
+    for (const [k, v] of Object.entries(node)) {
+      out[k] = k === 'failureGroups' && Array.isArray(v)
+        ? v.map((g) => (g && typeof g === 'object' ? redactTaskFailureGroup(g                     ) : g))
+        : redactFailureGroups(v);
+    }
+    return out     ;
+  }
+  return node;
+}
+
 // Spark config keys ending in `host`/`hostname` (e.g. spark.driver.host,
 // spark.yarn.am.hostname) carry plain FQDN host names that neither
 // HOST_PATTERNS matches (no IP/EC2 shape) nor collectHostFields's by-key-name
 // walk catches (the literal key is the dotted Spark property name, never
 // `host` itself). app.config is a flat Record<string, string> unique to
-// redactExportData: no other redact* export ships a raw Spark config dict.
+// redactRunModel: no other redact* export ships a raw Spark config dict.
 // Known gap: a hostname value under a differently-named key isn't caught by
 // this suffix check. Confirmed against a real cluster config: spark.master,
 // spark.yarn.historyServer.address, and the plural YARN proxy/HA keys
@@ -172,29 +188,12 @@ function applyReplacements   (node   , ids
   return deepReplace(node, merged)     ;
 }
 
-export function redactReport                            (report   )    {
+export function redactReport                            (input   )    {
+  const report = redactFailureGroups(input);
   const { appIds, hosts } = collectIds(report);
   return applyReplacements(report, { appIds, hosts });
 }
 
-// Narrow counterpart to redactReport(), for getRunSummary()'s standalone app
-// object (no findings tree to walk). There's exactly one app id here, so no
-// Set/Map/sort is needed for it; name/sparkVersion still go through the
-// shared host/IP scan-and-replace since either can carry a host token as
-// free text.
-export function redactAppIdentity(
-  app                                                                         ,
-)                                                                          {
-  const hosts = new Set        ();
-  scanHostTokens(app.name, hosts);
-  scanHostTokens(app.sparkVersion, hosts);
-  return {
-    id: typeof app.id === 'string' && app.id.length > 0 ? 'app-1' : app.id,
-    name: applyReplacements(app.name, { hosts }),
-    sparkVersion: applyReplacements(app.sparkVersion, { hosts }),
-  };
-}
-
 // Run-comparison counterpart: no single app-id *field* to pseudonymize
 // (baselineLabel/candidateLabel are caller-supplied labels, not Spark app
 // ids), but stage names surface throughout the tree (FindingsDeltaRow.stages,
@@ -216,7 +215,10 @@ export function redactComparison   (comparison   )    {
 // this also walks executors.added/removed for their literal `host` field
 // (ExecutorAddedEvent.host), since raw executor records: not just findings
 //: reach data.js.
-export function redactExportData(data               )                {
+                                                                                       
+
+function redactRunTree                   (input   )    {
+  const data = redactFailureGroups(input);
   const appIds = new Set        ();
   const hosts = new Set        ();
   const appId = data.app?.id;
@@ -229,3 +231,41 @@ export function redactExportData(data               )                {
   scanTokens(data, [{ patterns: HOST_PATTERNS, out: hosts }, { patterns: APP_ID_PATTERNS, out: appIds }]);
   return applyReplacements(data, { appIds, hosts });
 }
+
+/** A run's model and findings with every identifier pseudonymized. Redact this before anything derives
+ * text from the run: the verdict truncates Spark's failure reason, and an
+ * identifier cut by that truncation is a fragment no later pass can match. */
+export function redactRunModel(
+  appModel          ,
+  catalog           ,
+  configFindings           ,
+)                                                                        {
+  // Maps and Sets would lose their entries in the deep copy, so they cross as
+  // tagged plain objects, the way the export payload carries them.
+  const tree = encodeCollections({
+    app: appModel.app,
+    stages: [...appModel.stages.values()],
+    jobs: [...appModel.jobs.values()],
+    sql: [...appModel.sql.values()],
+    executors: appModel.executors,
+    runAggregates: appModel.runAggregates,
+    evidenceAvailability: appModel.evidenceAvailability,
+    catalog,
+    configFindings,
+  })                                                                                                                           ;
+  const redacted = decodeCollections(redactRunTree(tree))               ;
+  const byId =                           (items           ) => new Map((items       ).map((item) => [item.id, item]));
+  return {
+    appModel: {
+      app: redacted.app,
+      stages: byId(redacted.stages),
+      jobs: byId(redacted.jobs),
+      sql: byId(redacted.sql),
+      executors: redacted.executors,
+      runAggregates: redacted.runAggregates                             ,
+      evidenceAvailability: redacted.evidenceAvailability                                    ,
+    }            ,
+    catalog: redacted.catalog,
+    configFindings: redacted.configFindings,
+  };
+}

package/vendor-core/run-comparison.js

@@ -2,8 +2,12 @@ import { computeWallClock } from './wall-clock.js';
 import { normalizeDetail } from './detectors.js';
 import { cyrb53 } from './string-hash.js';
 import { captureSnapshot } from './session-snapshot.js';
-                                                                                   
+import { tunedRunNote } from './threshold-overrides.js';
+                                                                                                    
                                                              
+                                                                                        
+import { isIncompleteRun } from './check-coverage.js';
+import { summarizeRunOutcome } from './run-outcome.js';
 
                                  
                              
@@ -12,7 +16,7 @@ import { captureSnapshot } from './session-snapshot.js';
                              
  
                                    
-                                                                                                          
+                                                                                                                        
  
                                     
                                                 
@@ -23,7 +27,16 @@ import { captureSnapshot } from './session-snapshot.js';
                                                                                                                                                   
                                                                             
                                                                             
+                                                                                            
+                                                                                               
+                                   
+                                                                             
  
+
+function jobOutcome(snapshot                 )                    {
+  const { failedJobs, totalJobs } = summarizeRunOutcome(snapshot.jobs, snapshot.catalog);
+  return { failedJobs, totalJobs, incomplete: isIncompleteRun(snapshot.catalog) };
+}
 
 // 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.
@@ -180,6 +193,14 @@ function skewRatios(stages         )           {
   return out;
 }
 
+// Every key metricDeltas() emits, in emission order. The CLI validates
+// --regression-metric against it, so a misspelled key is a usage error rather
+// than an inconclusive budget. A contract test keeps it in sync.
+export const COMPARISON_METRIC_KEYS                    = [
+  'wallClock', 'shuffleSpill', 'taskSkew', 'failedTaskRate', 'diskSpill', 'gcTime',
+  'inputBytes', 'outputBytes', 'executorRunTime', 'taskCount', 'executorsAdded',
+];
+
 // 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
@@ -274,14 +295,14 @@ export function metricDeltas(baseSnap                 , candSnap
 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 rule = 'rule' in f && 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        () };
+      const e = m.get(key) ?? { rule, type: f.type, 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.
@@ -300,7 +321,7 @@ export function findingsDelta(baseSnap                 , candSnap
     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,
+    const row                   = { rule: meta.rule, type: meta.type, impactBand: meta.impactBand, baseCount, candCount,
       delta: candCount - baseCount, stages: [...more.stages].sort() };
     (candCount > baseCount ? introduced : resolved).push(row);
   }
@@ -420,6 +441,7 @@ export function compareRuns(
     stageSkew: stageSkewDeltas(baseSnap, candSnap, match),
     baseStages: stageList(baseSnap),
     candStages: stageList(candSnap),
+    jobOutcomes: { baseline: jobOutcome(baseSnap), candidate: jobOutcome(candSnap) },
   };
 }
 
@@ -437,8 +459,19 @@ function renderFindingsSection(title        , findings                    )
 // 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                   )         {
+/** `tuned`: tunedDetectors() for the overrides both runs were analyzed with, named in the output
+ * as the evidence report names them. */
+export function renderComparisonMarkdown(
+  comparison                   , verdict                        , tuned                                         ,
+)         {
   const lines = ['', '## Comparison to baseline', ''];
+  if (tuned) lines.push(`- Tuned thresholds (both runs): ${tunedRunNote(tuned)}`, '');
+  if (verdict) {
+    // The dashboard comparison page's headline: run A is the baseline, run B the candidate.
+    lines.push(`Run A: ${comparison.baselineLabel} · Run B: ${comparison.candidateLabel}`, '', verdict.title);
+    if (verdict.sentences.length > 0) lines.push('', verdict.sentences.join(' '));
+    lines.push('');
+  }
   if (comparison.confidence === 'low') {
     lines.push(`- confidence: low, ${comparison.reason}`);
     lines.push('');

package/vendor-core/run-interpretation.js

@@ -0,0 +1,290 @@
+// The interpretation layer of a run as plain data: the verdict, which checks could not run and
+// why, every finding's formatted savings, and the run-shape figures. Everything here can change
+// the conclusion about a run, so it is computed once, by the core that ran the detectors, and
+// handed to the renderer as data. The live dashboard (useIngest) and both HTML-export producers
+// (html-export.ts) call `interpretRun`; the exported bundle only renders what it carries, so an
+// exported file shows the conclusions of the core that wrote it, not of the core that opens it.
+import { checkCoverage, hasFinishedStage, verdictGaps } from './check-coverage.js';
+import { computeCoreLocalityRatio } from './core-locality-ratio.js';
+import { buildLocalityChart,                    } from './core-usage-locality.js';
+import { detectorInfoByType,                   } from './detector-docs.js';
+import { computeEfficiencyModel } from './efficiency-model.js';
+import { attributeEtlPhases } from './etl-phases.js';
+import { IMPACT_BAND_ORDER, worstImpactBand } from './format-utils.js';
+import {
+  estimateProvenance, impactEstimateCompact, impactEstimateFigure, impactFigure, savingsMeaning,
+} from './impact-format.js';
+import { isEligible, rankedRollup,                        } from './recommendation-rollup.js';
+import { quotesReasonOf } from './run-outcome.js';
+import { computeRunShape,               } from './run-shape.js';
+import {
+  buildNextSteps, buildRunVerdict, FINDING_DISPLAY_ORDER, locationKey, quotedReasonText, rankBySavings, stepCopyText,
+} from './run-verdict.js';
+import { recommendationText } from './finding-names.js';
+import { getScorecardEstimates } from './scorecard-estimates.js';
+import { checkConcurrentJobGroups } from './job-groups.js';
+import { computeWallClock } from './wall-clock.js';
+import { computeWastedCoreHours,                            } from './wasted-core-hours.js';
+                                                    
+
+/** A finding's savings figures, formatted with their units, so a widget shows the figure
+ * without formatting it. */
+                                 
+                                                                                               
+                                                        
+                        
+                                                              
+                         
+                                                                                                  
+                       
+                                            
+                         
+                                                                            
+                            
+ 
+
+/** One verdict step, fully worded. `leadIndex` names the finding the step routes to. */
+                                  
+              
+                    
+                         
+                                                              
+                         
+                                                                                      
+                                 
+                         
+                                    
+                   
+ 
+
+                                 
+                
+                    
+                  
+                 
+                                                          
+                               
+                           
+                                                           
+                    
+                                                               
+                          
+ 
+
+                               
+                            
+                                                                                          
+                                        
+                                                                                          
+                 
+ 
+
+                                                          
+
+/** The Scorecard's three headline figures (the ones the report's runShape also states) and how
+ * each is graded. `wallClockMs` is null without a complete application timing interval. */
+                                                                                                             
+                                
+                                    
+                                                                                                            
+ 
+
+                                                                
+
+                                                                       
+
+                                                                  
+
+                                   
+                                          
+                       
+                                                                           
+                                                     
+ 
+
+/** A stage's findings as the stage dialog lists them, in the verdict's step order. */
+                                    
+                           
+                                                                                              
+                      
+ 
+
+/** One row group of the Findings board: a finding type (split by impact kind, and by unit for
+ * resource figures), its members representative first, the band it sits under, and its trailing
+ * figure. */
+                                                                             
+                                       
+                          
+ 
+
+/** The unfiltered Findings board: which findings it lists and its groups in fix-first order. */
+                             
+                            
+                            
+ 
+
+/** Findings are referred to by index into the run's findings in catalog-then-config order
+ * (`[...catalog, ...configFindings]`), the order both producers pass them in: no copies, so a
+ * renderer resolves them to the very objects it already holds. */
+                                    
+                                                                
+                            
+                          
+                         
+                         
+                                                                                           
+                           
+                                       
+                                         
+                                                                                    
+                                    
+                                                                                            
+                             
+                                        
+                           
+                                 
+                                                                              
+                                          
+                                                                      
+                        
+                                                                 
+                                            
+                     
+ 
+
+export function findingSavings(finding         )                 {
+  return {
+    figure: impactFigure(finding),
+    meaning: savingsMeaning(finding),
+    board: impactEstimateFigure(finding.impactEstimate)?.text ?? null,
+    compact: impactEstimateCompact(finding.impactEstimate),
+    provenance: estimateProvenance(finding),
+  };
+}
+
+// The Scorecard's severity rule: a tile is flagged only when the figure is bad enough to act on.
+function efficiencyFlag(pct               )                {
+  if (pct == null) return null;
+  return pct < 75 ? 'critical' : pct < 90 ? 'warning' : null;
+}
+
+function unusedCoreTimeFlag(pct               )                {
+  if (pct == null) return null;
+  return pct >= 70 ? 'critical' : pct >= 40 ? 'warning' : null;
+}
+
+function interpretRunShape(appModel          )               {
+  const { wallClockMs, efficiencyPct, unusedCoreTimePct } = computeRunShape(appModel);
+  const estimates = getScorecardEstimates(appModel);
+  return {
+    wallClockMs,
+    efficiencyPct,
+    unusedCoreTimePct,
+    efficiencyFlag: efficiencyFlag(efficiencyPct),
+    unusedCoreTimeFlag: unusedCoreTimeFlag(unusedCoreTimePct),
+    unusedCoreTimeUnavailableReason: estimates.wastage.unavailableReason,
+  };
+}
+
+function interpretEfficiency(appModel          )                        {
+  if (!appModel.runAggregates) return null;
+  return computeEfficiencyModel({
+    app: appModel.app,
+    stages: appModel.stages,
+    executorsAdded: appModel.executors.added,
+    runAggregates: appModel.runAggregates,
+  });
+}
+
+function interpretCoverage(appModel          , allFindings           )               {
+  const noFinishedStages = !hasFinishedStage(appModel.stages);
+  const { notRunReason } = checkCoverage(appModel.stages, allFindings);
+  const notRunReasons                         = {};
+  for (const type of FINDING_DISPLAY_ORDER) {
+    const reason = notRunReason(type);
+    if (reason != null) notRunReasons[type] = reason;
+  }
+  return { noFinishedStages, notRunReasons, gaps: verdictGaps(allFindings, noFinishedStages) };
+}
+
+// The stage dialog's grouping: the verdict's location rule (a sql-scope finding touching only
+// this stage counts), ordered by the stage's own verdict step, then by worst band.
+function interpretStages(
+  catalog           , indexOf                      , failedJobStageIds                            ,
+)                                    {
+  const byStage = new Map                   ();
+  for (const finding of catalog) {
+    const { stageId } = locationKey(finding);
+    if (stageId == null) continue;
+    const list = byStage.get(stageId) ?? [];
+    list.push(finding);
+    byStage.set(stageId, list);
+  }
+  const stages                                    = {};
+  for (const [stageId, findings] of byStage) {
+    const [step] = buildNextSteps(findings, failedJobStageIds ? { failedJobStageIds } : {});
+    const stepTypes = step ? [step.lead.type, ...step.related.map((f) => f.type)] : [];
+    const worstBand = (type        ) => IMPACT_BAND_ORDER[worstImpactBand(findings.filter((f) => f.type === type)) ];
+    const otherTypes = [...new Set(findings.map((f) => f.type))]
+      .filter((type) => !stepTypes.includes(type))
+      .sort((a, b) => worstBand(a) - worstBand(b));
+    stages[String(stageId)] = { findingIndexes: findings.map((f) => indexOf.get(f) ), typeOrder: [...stepTypes, ...otherTypes] };
+  }
+  return stages;
+}
+
+const DISPLAY_TYPES                      = new Set(FINDING_DISPLAY_ORDER);
+
+/** Every conclusion the dashboard shows about a run whose detectors already ran. */
+export function interpretRun(appModel          , catalog           , configFindings           )                    {
+  const allFindings = [...catalog, ...configFindings];
+  const indexOf = new Map(allFindings.map((finding, index) => [finding, index]));
+  const verdict = buildRunVerdict(appModel, allFindings);
+  const { outcome } = verdict;
+  const failed = outcome.failedJobs > 0;
+  // A board row needs a widget to route to, and every display type has one.
+  const eligible = allFindings.filter((finding) => isEligible(finding) && DISPLAY_TYPES.has(finding.type));
+  const steps                    = verdict.shown.map((step) => {
+    const quoted = quotesReasonOf(step.lead, outcome) && outcome.reason ? quotedReasonText(outcome.reason) : null;
+    return {
+      key: step.key,
+      leadIndex: indexOf.get(step.lead) ,
+      stageId: step.stageId,
+      relatedTypes: step.related.map((f) => f.type),
+      recommendation: quoted?.shown ?? recommendationText(step.lead),
+      copyText: stepCopyText(step.lead, quoted?.copied ?? recommendationText(step.lead)),
+    };
+  });
+  return {
+    savings: allFindings.map(findingSavings),
+    verdict: {
+      title: verdict.title,
+      summary: verdict.summary,
+      failed,
+      clean: verdict.facts.clean,
+      failureReason: outcome.reason,
+      steps,
+      remaining: verdict.remaining,
+      copyText: verdict.copyText,
+    },
+    coverage: interpretCoverage(appModel, allFindings),
+    runShape: interpretRunShape(appModel),
+    wallClock: computeWallClock(appModel.app, appModel.stages),
+    wastedCoreHours: computeWastedCoreHours(appModel.app, appModel.executors.added, appModel.runAggregates),
+    efficiency: interpretEfficiency(appModel),
+    wallClockReliable: checkConcurrentJobGroups(appModel.jobs).wallClockReliable,
+    etlPhases: attributeEtlPhases(appModel.stages),
+    coreLocality: {
+      chart: buildLocalityChart([...appModel.stages.values()], appModel.app),
+      ratio: computeCoreLocalityRatio([...appModel.stages.values()], { topN: Infinity }),
+    },
+    detectors: detectorInfoByType(),
+    savingsRank: rankBySavings(allFindings).map((finding) => indexOf.get(finding) ),
+    stages: interpretStages(catalog, indexOf, failed ? outcome.failedJobStageIds : null),
+    rollup: {
+      eligibleIndexes: eligible.map((finding) => indexOf.get(finding) ),
+      groups: rankedRollup(eligible, appModel.stages)
+        .map(({ members, ...group }) => ({ ...group, memberIndexes: members.map((finding) => indexOf.get(finding) ) })),
+    },
+  };
+}

package/vendor-core/run-outcome.js

@@ -0,0 +1,74 @@
+                                                          
+
+/** Finding types that mean work did not finish: a stage attempt that failed
+ * outright, and jobs that ended without succeeding. Failed tasks that a retry
+ * recovered (`failures`) are not in this set: the run still completed. */
+export const FAILURE_TYPES                      = new Set(['stageFailed', 'jobFailureRate']);
+
+/** Longest failure reason the verdict quotes; Spark reasons can carry a whole
+ * stack trace, and the first line already names the cause. */
+export const FAILURE_REASON_MAX_CHARS = 240;
+
+/** How the run ended, as far as its jobs say. `failedJobs` and `totalJobs`
+ * count only jobs with an end record, so a job still running when an
+ * incomplete log stops is neither. */
+                             
+                     
+                    
+                                                                          
+                                         
+                                                                           
+                                  
+                        
+                                                                            
+                                                
+                               
+ 
+
+function firstLine(text        )                {
+  const line = text.split('\n')[0].trim();
+  if (line.length === 0) return null;
+  return line.length > FAILURE_REASON_MAX_CHARS ? `${line.slice(0, FAILURE_REASON_MAX_CHARS - 3).trimEnd()}...` : line;
+}
+
+function exceptionText(exception         )                {
+  if (typeof exception === 'string') return exception;
+  return null;
+}
+
+/** Summarizes the run's job results. The reason prefers a failed stage that
+ * belongs to a failed job (the stage is the nearer cause), then any failed
+ * stage, then the first failed job's exception message. */
+export function summarizeRunOutcome(jobs                  , findings           )             {
+  const ended = [...jobs.values()].filter((job) => job.result != null);
+  const failed = ended.filter((job) => job.succeeded === false).sort((a, b) => a.id - b.id);
+  const failedStageIds = new Set(failed.flatMap((job) => job.stageIds));
+  const stageReasons = findings
+    .filter((finding)                                      => finding.type === 'stageFailed')
+    .sort((a, b) => Number(failedStageIds.has(b.stageId          )) - Number(failedStageIds.has(a.stageId          )));
+  const stageSource = stageReasons[0];
+  const rawReason =
+    stageSource?.valueText
+    ?? failed.map((job) => exceptionText(job.exception)).find((text) => text != null)
+    ?? null;
+  return {
+    failedJobs: failed.length,
+    totalJobs: ended.length,
+    failedJobStageIds: failedStageIds,
+    reason: failed.length > 0 && rawReason != null ? firstLine(rawReason) : null,
+    reasonStageId: stageSource?.stageId ?? null,
+  };
+}
+
+/** Whether the quoted reason is this finding's own: the stage failure whose
+ * first line it is, or the job-failure finding when exactly one job failed
+ * and the reason belongs to that job. Any other failure has a cause the
+ * verdict does not show. */
+export function quotesReasonOf(finding         , outcome            )          {
+  if (outcome.reason == null) return false;
+  if (finding.type === 'stageFailed') return firstLine(finding.valueText) === outcome.reason;
+  if (finding.type === 'jobFailureRate') {
+    return outcome.failedJobs === 1 && (outcome.reasonStageId == null || outcome.failedJobStageIds.has(outcome.reasonStageId));
+  }
+  return false;
+}

package/vendor-core/run-payload.js

@@ -0,0 +1,17 @@
+// How an encoded HTML-export payload reaches the export app: a window global
+// that data.js (or the inlined script) assigns and main-export.tsx reads.
+// Dependency-free, so the export bundle can read the global without pulling in
+// the producer side (html-export.ts and the analysis it runs).
+
+/** The window global the payload statement assigns and the export app reads. */
+export const RUN_PAYLOAD_GLOBAL = '__SPARKFORENSICS_RUN_GZ__';
+
+/** The one JavaScript statement that hands an encoded payload to the export
+ * app. base64's alphabet (A-Za-z0-9+/=) can't contain "<" or a quote, so log
+ * free text can't inject a "</script>" break-out or end the string literal:
+ * the statement is safe to place inside an inline <script> with no escaping.
+ * That only holds while `base64` really is base64; keep any new encoding
+ * inside that alphabet or escape it here. */
+export function runPayloadScript(base64        )         {
+  return `window.${RUN_PAYLOAD_GLOBAL} = "${base64}";`;
+}