sparkforensics-cli 0.1.0 → 0.2.0

package/vendor-core/plan-graph-model.js

@@ -1,26 +1,24 @@
 // Flattens a resolved planTree into a { nodes, edges } graph shape for the
 // React Flow + Dagre plan graph view ("Plan graph view" in
-// docs-site/contributor-guide/architecture/drill-down.md). Every Exchange
-// node is split into paired write/read halves: the
-// write half stays with its children's producer segment and the read half
-// stays with its parent's consumer segment. A duration share stays on the
-// half in the original source node's attributed segment. Both halves share a
-// `sourceNodeId` back-reference to the pre-split node's id, so any aggregate
-// logic over nodes never double-counts one Exchange.
+// docs-site/contributor-guide/architecture/drill-down.md). The Exchange
+// write/read split is done upstream now, in resolvePlanTree
+// (event-handlers.ts): this file just walks the already-split tree and maps
+// each real PlanNode onto a PlanGraphNodeData. sourceNodeId still lets a
+// write half point back to its read half's id, so aggregate logic over
+// nodes can group a pair without special-casing exchangeRole everywhere.
 import { walkPlanTree } from './plan-tree-walk.js';
 import {
   classifyNode,
   buildDurationMap,
   parseOperatorDetail,
   getPrimaryMetric,
+  formatPlanMetricValue,
 } from './plan-node-detail.js';
 import { computeSegments, mapSegmentsToStagesForDisplay } from './plan-duration-attribution.js';
 import { stageIdsForSqlExec } from './detectors.js';
+             
                                                                                                        
-
-function isExchangeNode(node          )          {
-  return classifyNode(node.name) === 'exchange';
-}
+                    
 
 function makeGraphNode({
   id,
@@ -30,6 +28,8 @@ function makeGraphNode({
   segmentIndex,
   splitRole,
   durationShare,
+  exclusiveDurationShare,
+  findings,
 }   
              
                        
@@ -38,6 +38,8 @@ function makeGraphNode({
                        
                                      
                                 
+                                         
+                      
  )                    {
   return {
     id,
@@ -49,21 +51,29 @@ function makeGraphNode({
     segmentIndex,
     splitRole,
     durationShare: durationShare ?? null,
+    exclusiveDurationShare: exclusiveDurationShare ?? null,
+    findings,
+    metrics: (planNode.metrics ?? []).map((m) => ({ name: m.name, value: formatPlanMetricValue(m) })),
+    // Drop a detail that only repeats the operator name (no extra information
+    // for the card); parseOperatorDetail already treats that case as empty.
+    detailText: planNode.detail && planNode.detail !== planNode.name ? planNode.detail : '',
   };
 }
 
 export function buildPlanGraphModel(
   planTree                 ,
-  opts                                                                    ,
+  opts   
+                              
+                    
+                       
+                         
+                                         
+   ,
 )                 {
-  const { scope, stageId, appModel } = opts;
+  const { scope, stageId, appModel, findings = [], durationMode = 'exclusive' } = opts;
   if (!planTree) return { nodes: [], edges: [], segmentIndex: null, segmentCount: 0, scope: 'full', segmentStageIds: new Map                () };
 
   const stage = appModel.stages.get(stageId);
-  // Coalesce undefined -> null so `sqlExecutionId` has a stable `number | null`
-  // type: every branch below narrows off the same variable instead of
-  // re-deriving it from `stage`, which TS can't re-narrow after the `stage?.`
-  // optional-chain expression above collapses to a plain boolean.
   const sqlExecutionId = stage?.sqlExecutionId ?? null;
   const sqlExec = sqlExecutionId != null ? appModel.sql.get(sqlExecutionId) : null;
 
@@ -71,20 +81,21 @@ export function buildPlanGraphModel(
   const segmentCount = segments.filter(Boolean).length;
 
   const durationMap =
-    sqlExec && sqlExecutionId != null ? buildDurationMap(planTree, appModel, sqlExec, sqlExecutionId) : null;
-
-  // Segment -> stage-id association, computed once up front regardless of
-  // `scope`: 'segment' needs it below to resolve which segment `stageId`
-  // belongs to, and 'full' needs the same map to label each segment's
-  // compound-group header (Task 11) with its stage id; it must not be
-  // computed only inside the 'segment' branch, or the full-plan view would
-  // have no stage-id data for its group headers. mapSegmentsToStagesForDisplay
-  // fills in segments that lost the strict zip's Math.min(segments, stages)
-  // pairing slot from their nearest paired neighbor, so a group box only
-  // falls back to an unexplained "Stage —" when there's truly no stage to
-  // borrow from (see its own doc comment); the earlier `targetSegmentIndex`
-  // lookup below stays correct either way, since a strictly-paired segment's
-  // canonical entry is always inserted before any inherited duplicate.
+    sqlExec && sqlExecutionId != null ? buildDurationMap(planTree, appModel, sqlExec, sqlExecutionId, durationMode) : null;
+  // A second, always-exclusive map, independent of the requested `durationMode`.
+  // Exclusive shares are a true, non-overlapping partition of each paired
+  // stage's wall time (computeExclusiveSharesForPairs), so their sum is a
+  // stable normalization total. PlanGraphCanvas needs this alongside
+  // `durationMap` (the mode-selected values actually shown) because summing
+  // `durationMap` itself would double/triple-count under 'inclusive' mode,
+  // where an ancestor's share already folds in every descendant's share.
+  // durationMode === 'exclusive' already computed the same map above; only
+  // redo the work when the requested mode actually differs.
+  const exclusiveDurationMap =
+    durationMode === 'exclusive'
+      ? durationMap
+      : sqlExec && sqlExecutionId != null ? buildDurationMap(planTree, appModel, sqlExec, sqlExecutionId, 'exclusive') : null;
+
   const segmentStageIds = new Map                ();
   const linkedStageIds           =
     sqlExec && sqlExecutionId != null ? stageIdsForSqlExec(sqlExecutionId, appModel.stages) : [];
@@ -99,50 +110,99 @@ export function buildPlanGraphModel(
     }
   }
 
-  // A full walk always happens first (cheap: one tree pass), splitting
-  // every Exchange and tagging each half's own segmentIndex correctly.
-  // Scope filtering is a post-pass over this output, since a split node's
-  // two halves can land in two different segments (see module doc comment)
-  // and a pre-split per-original-node filter can't express that.
-  const idOf = new WeakMap                  ();
-  let counter = 0;
+  // resolvePlanTree (event-handlers.ts) now prefixes every id with its owning
+  // execution, but this filter stays as defense in depth: a finding is scoped
+  // to the execution whose graph is being built before it's indexed by node
+  // id, so a stale/synthetic finding whose planNodeIds happen to collide with
+  // this tree's ids (e.g. hand-built test fixtures, or data from before the
+  // prefix existed) still can't badge onto the wrong tree. No linked SQL
+  // execution means no findings attach, matching the sqlExec-falsy behavior
+  // used elsewhere in this function (durationMap, linkedStageIds).
+  const findingsByNodeId = new Map                   ();
+  if (sqlExecutionId != null) {
+    for (const finding of findings) {
+      if (finding.executionId !== sqlExecutionId) continue;
+      for (const nodeId of finding.planNodeIds ?? []) {
+        const list = findingsByNodeId.get(nodeId);
+        if (list) list.push(finding);
+        else findingsByNodeId.set(nodeId, [finding]);
+      }
+    }
+  }
+
   const allNodes                      = [];
   const allEdges                  = [];
 
+  // Both halves of one split Exchange share a sourceNodeId (the read half's id:
+  // the read half points at itself, the write half at its read parent). Collect
+  // them under that key during the walk so the post-pass below can cross-link
+  // the pair and mirror the shuffle-boundary bytes onto both halves, even
+  // though only one half is visible from any single-segment view.
+  const splitPairs = new Map                                                                                        ();
+
   walkPlanTree(planTree, (node, parent) => {
-    const id = `n${counter++}`;
+    // resolvePlanTree always sets id; safe downstream of it.
+    const id = node.id ;
     const category = classifyNode(node.name);
-    // computeSegments (above) already walked this same planTree with the
-    // same `{ dedupe: true }` traversal, so every node this walk visits is
-    // guaranteed to already have a segOf entry; the `!` reflects that
-    // invariant, not an actual nullable field.
     const seg = segOf.get(node) ;
-    const parentId = parent ? idOf.get(parent) : null;
-
-    if (isExchangeNode(node)) {
-      const readId = `${id}-read`;
-      const writeId = `${id}-write`;
-      const writeSegment = node.children?.length ? segOf.get(node.children[0])  : seg;
-      allNodes.push(makeGraphNode({
-        id: readId, sourceNodeId: id, planNode: node, category, segmentIndex: seg, splitRole: 'read',
-        durationShare: durationMap?.get(node),
-      }));
-      allNodes.push(makeGraphNode({
-        id: writeId, sourceNodeId: id, planNode: node, category, segmentIndex: writeSegment, splitRole: 'write',
-      }));
-      allEdges.push({ id: `${readId}=>${writeId}`, source: readId, target: writeId });
-      if (parentId) allEdges.push({ id: `${parentId}->${readId}`, source: parentId, target: readId });
-      idOf.set(node, writeId);
-    } else {
-      allNodes.push(makeGraphNode({
-        id, sourceNodeId: id, planNode: node, category, segmentIndex: seg, splitRole: null,
-        durationShare: durationMap?.get(node),
-      }));
-      if (parentId) allEdges.push({ id: `${parentId}->${id}`, source: parentId, target: id });
-      idOf.set(node, id);
+    const parentId = parent ? parent.id  : null;
+    const sourceNodeId = node.exchangeRole === 'write' && parent ? parent.id  : id;
+
+    const graphNode = makeGraphNode({
+      id,
+      sourceNodeId,
+      planNode: node,
+      category,
+      segmentIndex: seg,
+      splitRole: node.exchangeRole ?? null,
+      durationShare: durationMap?.get(node),
+      exclusiveDurationShare: exclusiveDurationMap?.get(node),
+      findings: findingsByNodeId.get(id) ?? [],
+    });
+    allNodes.push(graphNode);
+    if (node.exchangeRole) {
+      const entry = splitPairs.get(sourceNodeId) ?? {};
+      entry[node.exchangeRole] = graphNode;
+      splitPairs.set(sourceNodeId, entry);
+    }
+    if (parentId) {
+      const edge                = { id: `${parentId}->${id}`, source: parentId, target: id };
+      // The read->write pairing edge is the shuffle boundary: weight it by the
+      // bytes written across it. The write half lives in the producer segment,
+      // and its stage's shuffleWriteBytes is exactly the data materialized to
+      // this shuffle, falling back to shuffleReadBytes when the write side
+      // wasn't captured. Zero/absent on both means no weight, so a broadcast
+      // (which moves little by design) or an empty exchange stays a plain edge.
+      if (node.exchangeRole === 'write') {
+        const producingStageId = segmentStageIds.get(seg);
+        const producingStage = producingStageId != null ? appModel.stages.get(producingStageId) : undefined;
+        const shuffleBytes = producingStage?.shuffleWriteBytes || producingStage?.shuffleReadBytes;
+        if (shuffleBytes) {
+          edge.shuffleBytes = shuffleBytes;
+          const entry = splitPairs.get(sourceNodeId) ?? {};
+          entry.shuffleBytes = shuffleBytes;
+          splitPairs.set(sourceNodeId, entry);
+        }
+      }
+      allEdges.push(edge);
     }
   }, { dedupe: true });
 
+  // Cross-link each Exchange pair and mirror the shuffle-boundary bytes onto
+  // both halves, so the detail card can reach the partner and show the volume
+  // whichever half is open. Runs over the full node set before any scope
+  // filtering, so pairedNodeId stays set even when the partner is scoped out.
+  for (const { read, write, shuffleBytes } of splitPairs.values()) {
+    if (read && write) {
+      read.pairedNodeId = write.id;
+      write.pairedNodeId = read.id;
+    }
+    if (shuffleBytes != null) {
+      if (read) read.exchangeShuffleBytes = shuffleBytes;
+      if (write) write.exchangeShuffleBytes = shuffleBytes;
+    }
+  }
+
   if (scope === 'full') {
     return { nodes: allNodes, edges: allEdges, segmentIndex: null, segmentCount, scope: 'full', segmentStageIds };
   }
@@ -153,9 +213,6 @@ export function buildPlanGraphModel(
   }
 
   if (targetSegmentIndex === null) {
-    // Segment lookup failed (no sql/stage linkage, or this stage's segment
-    // fell outside the Math.min(segments, stages) truncation), fall back
-    // to full-plan scope rather than showing nothing.
     return { nodes: allNodes, edges: allEdges, segmentIndex: null, segmentCount, scope: 'full', segmentStageIds };
   }
 

package/vendor-core/plan-node-detail.js

@@ -1,13 +1,12 @@
 // Per-operator plan-node rendering helpers for the stage-detail modal's
-// hierarchical plan tree. Ported near-verbatim from the legacy canvas widget
-// (src/widgets/stage-detail.js, deleted at 1db5365): pure string-parsing /
-// tree-walking logic, no DOM. Per AGENTS.md, plan-text parsing is
-// best-effort: unparseable fragments are silently skipped, never thrown.
+// hierarchical plan tree. Pure string-parsing / tree-walking, no DOM.
+// Plan-text parsing is best-effort: unparseable fragments are silently
+// skipped, never thrown.
 
 import { pathBasename, formatBytes, formatDuration } from './format-utils.js';
-import { attributeStageDurationToPlan } from './plan-duration-attribution.js';
+import { attributeStageDurationToPlan, attributeStageDurationToPlanInclusive } from './plan-duration-attribution.js';
 import { stageIdsForSqlExec } from './detectors.js';
-                                                                   
+                                                                                          
 
 const BOILERPLATE_PREFIXES = ['serializefromobject', 'deserializetoobject', 'mapelements',
   'mappartitions', 'inputadapter', 'columnartorow', 'rowtocolumnar', 'union'];
@@ -27,6 +26,14 @@ export function classifyNode(
   return 'transform';
 }
 
+export function isExchangeNode(node                                         )          {
+  return node.exchangeRole !== undefined || classifyNode(node.name) === 'exchange';
+}
+
+export function isBroadcastExchangeNode(name        )          {
+  return name === 'BroadcastExchange';
+}
+
 export function parseOperatorDetail(name        , simpleString        )         {
   if (!simpleString || simpleString === name) return '';
   const n = (name ?? '').toLowerCase();
@@ -112,11 +119,16 @@ export function parseOperatorDetail(name        , simpleString        )
     return fmtM ? fmtM[1] : '';
   }
 
-  const stripped = stripAliases(simpleString);
+  // Some operators (e.g. InMemoryTableScan) have no dedicated branch above, so
+  // their simpleString falls through here unparsed and repeats the operator
+  // name verbatim as a prefix ("InMemoryTableScan [DATE#1, COUNTRY#2, ...]"),
+  // which would otherwise duplicate the bold node name shown right next to it.
+  const escapedName = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const stripped = stripAliases(simpleString).replace(new RegExp(`^${escapedName}\\s*`, 'i'), '').trim();
   return stripped.length > 80 ? stripped.slice(0, 80) + '…' : stripped;
 }
 
-export function formatMetricValue(metric                                                 )         {
+export function formatPlanMetricValue(metric                                                 )         {
   const { value, metricType } = metric;
   if (typeof value === 'string') return value;
   if (metricType === 'size') return formatBytes(value);
@@ -131,17 +143,18 @@ export function getPrimaryMetric(
   if (!metrics || metrics.length === 0) return '';
   const priority = ['number of output rows', 'size of files read', 'spill size', 'duration'];
   const found = priority.map(n => metrics.find(m => m.name === n)).find(Boolean) ?? metrics[0];
-  return formatMetricValue(found);
+  return formatPlanMetricValue(found);
 }
 
-// Approximate per-node wall-time (dataflint-style segment attribution): see
-// attributeStageDurationToPlan. Returns null when there's nothing to attribute
-// (no plan tree, or the SQL execution doesn't carry a stageIds list).
+// Approximate per-node wall-time via segment attribution (see
+// attributeStageDurationToPlan). Returns null when there's nothing to attribute
+// (no plan tree, or the SQL execution carries no stageIds list).
 export function buildDurationMap(
   planTree                 ,
   appModel          ,
   sqlExec              ,
   executionId        ,
+  durationMode                        = 'exclusive',
 )                               {
   if (!planTree || !sqlExec) return null;
   const stageIds           = stageIdsForSqlExec(executionId, appModel.stages);
@@ -151,9 +164,10 @@ export function buildDurationMap(
     const s = appModel.stages.get(id);
     if (s) stagesById.set(id, { submittedAt: s.submittedAt, completedAt: s.completedAt });
   }
-  // attributeStageDurationToPlan still reads its 3rd arg's own `.stageIds`
-  // field internally (Task 2 didn't change that signature); override it
-  // with the derived array rather than the (always-empty, on real data)
-  // one already on `sqlExec`, without needing to change that function.
-  return attributeStageDurationToPlan(planTree, stagesById, { ...sqlExec, stageIds });
+  // attributeStageDurationToPlan reads its 3rd arg's own `.stageIds` field;
+  // override it with the derived array rather than the (always-empty on real
+  // data) one already on `sqlExec`.
+  return durationMode === 'inclusive'
+    ? attributeStageDurationToPlanInclusive(planTree, stagesById, { ...sqlExec, stageIds })
+    : attributeStageDurationToPlan(planTree, stagesById, { ...sqlExec, stageIds });
 }

package/vendor-core/plan-summary.js

@@ -1,11 +1,10 @@
 // Best-effort summary of a resolved plan tree (parser-worker `resolvePlanTree`).
-// Per AGENTS.md the plan surface is best-effort: unparseable fragments are
-// silently skipped, never surfaced as an error. This replaces the old regex
-// `plan-extractor.js`: the single plan representation is the tree.
+// Unparseable fragments are silently skipped, never surfaced as an error.
 
                                            
 import { pathBasename } from './format-utils.js';
 import { walkPlanTree } from './plan-tree-walk.js';
+import { isExchangeNode } from './plan-node-detail.js';
 
                                                                                                                              
                                                                                        
@@ -70,8 +69,8 @@ export function scanRelationId(name        , detail        )                {
   // 2. Internal Delta metadata (the _delta_log state scan and anonymous
   //    commit/checkpoint reads) → null. Location: is often truncated to `Del...`,
   //    so also key off DeltaLogFileIndex or the Delta-log action column signature.
-  //    ponytail: column-signature heuristic; a future Spark that renames those
-  //    action columns would leak a noise row; acceptable, verified clean on all 9 logs.
+  //    (Column-signature heuristic: a future Spark renaming those action columns
+  //    would leak a noise row; acceptable.)
   if (/_delta_log/.test(name) || /_delta_log/.test(detail) ||
       /DeltaLogFileIndex/i.test(name + detail) ||
       /checkpointMetadata#|sidecar#|commitInfo#/.test(name + detail)) {
@@ -181,7 +180,7 @@ export function summarizePlanTree(planTree                 )              {
     else if (visitScan(name, detail, result)) { /* handled */ }
     else if (/Join/i.test(name) && visitJoin(name, detail, result)) { /* handled */ }
     else if (/Aggregate/i.test(name) && visitAgg(name, detail, result)) { /* handled */ }
-    else if (/^Exchange/i.test(name)) visitExchange(detail, result);
+    else if (n.exchangeRole === 'read') visitExchange(detail, result);
     else if (/^Filter/i.test(name)) {
       const condM = detail.match(/^Filter\s+([\s\S]+)/);
       if (condM && condM[1].trim().length > 1000) pushLongFilterWarning(result, condM[1].trim().length);
@@ -204,18 +203,25 @@ export function describePlanNode(
   const name = node.name ?? '';
   const detail = node.detail ?? '';
   const result              = { scans: [], joins: [], aggs: [], exchanges: [], warnings: [] };
+  let recognizedType                                                                       = null;
 
   if (/CartesianProduct/i.test(name) || /CartesianProduct/i.test(detail)) {
+    recognizedType = 'cartesian';
     pushCrossJoinWarning(result, 'CartesianProduct');
   } else if (visitScan(name, detail, result)) {
+    recognizedType = 'scan';
     // handled
   } else if (/Join/i.test(name) && visitJoin(name, detail, result)) {
+    recognizedType = 'join';
     // handled (a Cross join type may also have pushed a crossJoin warning)
   } else if (/Aggregate/i.test(name) && visitAgg(name, detail, result)) {
+    recognizedType = 'agg';
     // handled (a partial-aggregation pass pushes nothing into result.aggs)
-  } else if (/^Exchange/i.test(name)) {
+  } else if (isExchangeNode(node)) {
+    recognizedType = 'exchange';
     visitExchange(detail, result);
   } else if (/^Filter/i.test(name)) {
+    recognizedType = 'filter';
     const condM = detail.match(/^Filter\s+([\s\S]+)/);
     if (condM && condM[1].trim().length > 1000) pushLongFilterWarning(result, condM[1].trim().length);
   }
@@ -224,10 +230,15 @@ export function describePlanNode(
     : result.joins[0] ? 'join'
     : result.aggs[0] ? 'agg'
     : result.exchanges[0] ? 'exchange'
+    : recognizedType === 'exchange' && node.exchangeRole !== 'write' ? 'exchange' // ReusedExchange recognized as exchange but no pattern match; write halves stay null
     : null;
   const fields = result.scans[0] ?? result.joins[0] ?? result.aggs[0] ?? result.exchanges[0] ?? null;
   const warning = result.warnings[0] ?? null;
 
-  if (!kind && !warning) return null;
+  // Return null if no recognized type, or if it's agg/filter with no content/warning
+  if (!recognizedType) return null;
+  if ((recognizedType === 'agg' || recognizedType === 'filter') && !kind && !warning) return null;
+
+  // For exchange or other types, or if there's content/warning, return the object
   return { kind, warning, ...(fields ?? {}) };
 }

package/vendor-core/recommendation-rollup.js

@@ -1,10 +1,5 @@
-// Explicit .ts extensions (unlike a bundler, plain Node's ESM resolver -
-// the runtime bin/sparkforensics-analyze.mjs and src/mcp-tools.ts both run
-// under, now that src/evidence-report.ts imports this module too - requires
-// the exact specifier, not an extensionless one a bundler would resolve for
-// you): this file's prior only consumer, src/view/widgets/FixTheseFirst.tsx,
-// went through Vite, which tolerates the extensionless form, so this never
-// surfaced until the CLI/MCP path started importing it.
+// Explicit .ts extensions: plain Node's ESM resolver (the runtime CLI/MCP path
+// runs under) requires the exact specifier, unlike a bundler.
 import { mergeIntervals } from './wall-clock.js';
 import { worstImpactBand, IMPACT_BAND_ORDER } from './format-utils.js';
                                                                     
@@ -14,13 +9,10 @@ import { worstImpactBand, IMPACT_BAND_ORDER } from './format-utils.js';
                        
  
 
-/** The cross-finding grouping layer the spec calls for: given every stage
- * touched by a group of findings, collect their intervals and merge once
- * across the combined set, instead of summing each finding's own
- * already-clipped wallClock figure (which double-counts concurrent stages
- * across different findings of the same detector type). Reuses the generic
- * mergeIntervals primitive (src/wall-clock.ts) rather than widening the
- * single-finding-scoped estimateMultiStage/unionMs in src/occupancy.ts. */
+/** Cross-finding grouping: given every stage touched by a group of findings,
+ * merge their intervals once across the combined set, instead of summing each
+ * finding's own already-clipped wallClock figure (which double-counts
+ * concurrent stages across different findings of the same detector type). */
 export function computeStageUnionMs(
   stageIds          ,
   stages                            ,
@@ -124,36 +116,41 @@ export function buildRecommendationRollup(
     const kindDelta = KIND_ORDER[a.kind] - KIND_ORDER[b.kind];
     if (kindDelta !== 0) return kindDelta;
     if (a.kind === 'time' && b.kind === 'time') return b.recoverableMsHigh - a.recoverableMsHigh;
-    // resource/count groups carry no shared magnitude to rank by (spec section
-    // 5 forbids comparing incompatible units); break ties by worst impact band
-    // instead, the same tie-break FixTheseFirst used pre-consolidation.
+    // resource/count groups carry no shared magnitude to rank by (comparing
+    // incompatible units is forbidden); break ties by worst impact band instead.
     const aImpactBand = IMPACT_BAND_ORDER[worstImpactBand(a.findings) ?? 'info'] ?? 9;
     const bImpactBand = IMPACT_BAND_ORDER[worstImpactBand(b.findings) ?? 'info'] ?? 9;
     return aImpactBand - bImpactBand;
   });
 }
 
-/** True when a finding is a candidate for the "fix these first" ranking at
- * all. Shared by `src/evidence-report.ts` (CLI/MCP path) and
- * `src/view/widgets/FixTheseFirst.tsx` (the dashboard widget) so these two
- * hardcoded exclusions can't drift between the two surfaces (they used to be
- * duplicated, near-verbatim, in both files). Doesn't check
- * `REGISTRY[finding.type] != null` (FixTheseFirst.tsx's own extra check):
- * `REGISTRY` lives in a `.tsx` file, not importable from this core module;
- * FixTheseFirst.tsx layers that extra check on top of this one instead. */
+/** True when a finding is real evidence of an issue, as opposed to a mere
+ * evidence-unavailable caveat. Shared by `isEligible` below and by anything
+ * else that decides whether a REGISTRY type has "something to show" (an
+ * active widget card vs. a Clean-checks line): memoryUtilization's
+ * memoryBand/dataUnavailable variant reports a missing-evidence caveat
+ * (spark.eventLog.logStageExecutorMetrics=true not on for this run), not an
+ * optimization or a clean bill of health; the exact same fact already lives
+ * in the Evidence availability ledger's own `executorMetrics` entry
+ * (src/evidence-availability.ts), so it belongs there, not as its own card. */
+export function isRealFinding(finding         )          {
+  if (finding.type === 'memoryUtilization' && finding.variant === 'memoryBand' && finding.dataUnavailable) return false;
+  return true;
+}
+
+/** True when a finding is a candidate for the "fix these first" ranking.
+ * Shared by evidence-report.ts (CLI/MCP path) and FixTheseFirst.tsx (the
+ * dashboard widget) so these hardcoded exclusions can't drift between the two
+ * surfaces. Doesn't check `REGISTRY[finding.type] != null`: `REGISTRY` lives
+ * in a `.tsx` file, not importable from this core module, so FixTheseFirst.tsx
+ * layers that extra check on top of this one. */
 export function isEligible(finding         )          {
   // incompleteRun is a pipeline-completeness signal, not an addressable fix:
-  // hardcoded here by type, not read from Detector.fixEffort. That field
-  // exists only to back its own contract test today (tests/fix-effort.test.js);
-  // nothing in ranking/exclusion logic reads it.
+  // hardcoded here by type, not read from Detector.fixEffort. Unlike
+  // `isRealFinding`, this exclusion doesn't apply beyond the rollup: an
+  // incompleteRun finding still backs its own ordinary active widget card.
   if (finding.type === 'incompleteRun') return false;
-  // memoryUtilization's memoryBand/dataUnavailable variant reports a missing
-  // -evidence caveat (spark.eventLog.logStageExecutorMetrics=true not on for
-  // this run), not an optimization: the exact same fact already lives in the
-  // Evidence availability ledger's own `executorMetrics` entry
-  // (src/evidence-availability.ts), so it belongs there, not here.
-  if (finding.type === 'memoryUtilization' && finding.variant === 'memoryBand' && finding.dataUnavailable) return false;
-  return true;
+  return isRealFinding(finding);
 }
 
 /** Ranking tier for a single finding: time-based findings (a real `wallClock`
@@ -186,10 +183,9 @@ export function rankFindings(findings           )            {
     const tierDelta = tierOf(a) - tierOf(b);
     if (tierDelta !== 0) return tierDelta;
     if (tierOf(a) === TIER_TIME) {
-      // Same unit (ms) on both sides: the one comparison that is meaningful.
-      // .high, matching deriveImpactBand (src/impact-band.ts) and
-      // triage-target.ts, so this ordering, the badge color, and the "click
-      // to investigate" target all agree on the same figure.
+      // Same unit (ms) on both sides. Rank on .high, matching deriveImpactBand
+      // and triage-target.ts, so ordering, badge color, and the "click to
+      // investigate" target all agree on the same figure.
       return b.impactEstimate .wallClock .high - a.impactEstimate .wallClock .high;
     }
     return (IMPACT_BAND_ORDER[a.impactBand] ?? 9) - (IMPACT_BAND_ORDER[b.impactBand] ?? 9);