@crvouga/atlas 0.3.0 → 0.5.0

package/packages/visualizer/src/evidence/artifacts.tsx

@@ -0,0 +1,272 @@
+import type { LayerHeader, LayerRow } from '@crvouga/atlas/reports/evidence-types';
+import type { CheckDetail, EvidenceHolder } from '@crvouga/atlas/reports/evidence-detail';
+import { roleOfType } from '@crvouga/atlas/reports/evidence-detail';
+import { contentTypeOf } from '@crvouga/atlas/reports/media-types';
+import type { Annotation, Attachment, Attempt, Step } from '@crvouga/atlas/schema';
+import { useQuery } from '@tanstack/react-query';
+import { useMemo, type ReactNode } from 'react';
+
+import { reportAssetUrl, reportJson, reportText } from './api';
+import styles from './artifacts.module.css';
+import { duration, plural } from './format';
+import { StatusMark } from './marks';
+
+/**
+ * How one kind of attachment is shown. The first renderer that matches wins, so a new kind of artifact (a
+ * flame graph, a HAR, a coverage map) is one more entry, and an attachment nobody has a renderer for is still
+ * listed, with its name, what it is and a way to download it. Nothing here fails on what it does not know.
+ */
+export type ArtifactRenderer = {
+  readonly id: string;
+  readonly matches: (attachment: Attachment, type: string) => boolean;
+  /** `url` is where the bytes are, if they are anywhere a browser can reach; `path` is the report API path of a stored file. */
+  readonly render: (attachment: Attachment, context: { url: string | null; path: string | null; type: string }) => ReactNode;
+  /** Wide renderers take a whole row of the gallery. */
+  readonly wide?: boolean;
+};
+
+const mediaType = (attachment: Attachment) => (attachment.contentType ?? contentTypeOf(attachment.name)).split(';')[0]!.trim().toLowerCase();
+const label = (attachment: Attachment) => attachment.description ?? attachment.name;
+
+/** Only addresses a browser may follow: never `javascript:` or `data:` from a producer. */
+function safeUri(uri: string | undefined): string | null {
+  if (!uri) return null;
+  try {
+    const url = new URL(uri, 'https://atlas.invalid/');
+    return url.protocol === 'http:' || url.protocol === 'https:' ? uri : null;
+  } catch {
+    return null;
+  }
+}
+
+function TextValue({ attachment, path }: { attachment: Attachment; path: string | null }) {
+  const stored = useQuery({ queryKey: ['artifact-text', path ?? ''], queryFn: ({ signal }) => reportText(path!, signal), enabled: attachment.text === undefined && path !== null, staleTime: Number.POSITIVE_INFINITY, retry: false });
+  const raw = attachment.text ?? stored.data;
+  if (raw === undefined) return <p className={styles.where}>{stored.isError ? 'Could not be read.' : 'Loading…'}</p>;
+  const shown = raw.length > 200_000 ? raw.slice(0, 200_000) : raw;
+  const pretty = /json/.test(mediaType(attachment)) ? tryPretty(shown) : shown;
+  return (
+    <>
+      <pre className={styles.text}>{pretty}</pre>
+      {shown.length < raw.length && <p className={styles.where}>Showing the first 200 000 characters.</p>}
+    </>
+  );
+}
+
+function tryPretty(text: string) {
+  try {
+    return JSON.stringify(JSON.parse(text), null, 2);
+  } catch {
+    return text;
+  }
+}
+
+/** In order: the first that matches. Add to the front with {@link registerArtifactRenderer}. */
+export const artifactRenderers: ArtifactRenderer[] = [
+  { id: 'image', matches: (_, type) => type.startsWith('image/') && type !== 'image/svg+xml', render: (a, { url }) => (url ? <a href={url} target="_blank" rel="noreferrer"><img src={url} alt={label(a)} loading="lazy" width={a.width} height={a.height} /></a> : null) },
+  // SVG can carry script: shown as a picture only, never inlined.
+  { id: 'svg', matches: (_, type) => type === 'image/svg+xml', render: (a, { url }) => (url ? <img src={url} alt={label(a)} loading="lazy" /> : null) },
+  { id: 'video', wide: true, matches: (_, type) => type.startsWith('video/'), render: (a, { url }) => (url ? <video src={url} controls preload="metadata" aria-label={label(a)} /> : null) },
+  { id: 'audio', matches: (_, type) => type.startsWith('audio/'), render: (a, { url }) => (url ? <audio src={url} controls preload="none" aria-label={label(a)} /> : null) },
+  // A page snapshot runs nothing: the frame has no permissions and the file is served sandboxed.
+  { id: 'snapshot', wide: true, matches: (_, type) => type === 'text/html' || type === 'application/xhtml+xml', render: (a, { url }) => (url ? <iframe sandbox="" src={url} title={label(a)} loading="lazy" /> : null) },
+  { id: 'pdf', wide: true, matches: (_, type) => type === 'application/pdf', render: (a, { url }) => (url ? <iframe sandbox="" src={url} title={label(a)} loading="lazy" /> : null) },
+  { id: 'text', wide: true, matches: (a, type) => a.text !== undefined || type.startsWith('text/') || /(json|xml|yaml|x-ndjson|x-diff)/.test(type), render: (a, { path }) => <TextValue attachment={a} path={path} /> }
+];
+
+export function registerArtifactRenderer(renderer: ArtifactRenderer) {
+  artifactRenderers.unshift(renderer);
+}
+
+function sizeOf(bytes: number | undefined) {
+  if (bytes === undefined) return '';
+  if (bytes < 1024) return `${bytes} B`;
+  return bytes < 1024 * 1024 ? `${(bytes / 1024).toFixed(0)} KiB` : `${(bytes / 1024 / 1024).toFixed(1)} MiB`;
+}
+
+function Artifact({ attachment, layer }: { attachment: Attachment; layer: string }) {
+  const type = mediaType(attachment);
+  const path = attachment.bundleKey ? `/layers/${encodeURIComponent(layer)}/blobs/${attachment.bundleKey.split('/').map(encodeURIComponent).join('/')}` : null;
+  const url = path ? reportAssetUrl(path) : safeUri(attachment.uri);
+  const renderer = artifactRenderers.find((candidate) => candidate.matches(attachment, type));
+  const body = renderer?.render(attachment, { url, path, type });
+  return (
+    <li className={styles.figure} data-wide={renderer?.wide || undefined} data-role={attachment.role ?? roleOfType(type)}>
+      {body}
+      <figcaption>
+        <strong>{attachment.name}</strong>
+        {attachment.role && <span className={styles.role}>{attachment.role}</span>}
+        <span>{[type, sizeOf(attachment.bytes), attachment.durationMs ? duration(attachment.durationMs) : ''].filter(Boolean).join(' · ')}</span>
+        {url && <a href={url} download={attachment.name} target="_blank" rel="noreferrer">{body ? 'Download' : 'Open'}</a>}
+        {!url && attachment.text === undefined && <span>No file to show</span>}
+      </figcaption>
+    </li>
+  );
+}
+
+export function Attachments({ attachments, layer }: { attachments: readonly Attachment[]; layer: string }) {
+  if (!attachments.length) return null;
+  return (
+    <section aria-label="Attachments">
+      <h4>{plural(attachments.length, 'attachment', 'attachments')}</h4>
+      <ul className={styles.gallery}>
+        {attachments.map((attachment, index) => <Artifact key={`${attachment.id ?? attachment.name}:${index}`} attachment={attachment} layer={layer} />)}
+      </ul>
+    </section>
+  );
+}
+
+const STEP_STATUS: Record<string, 'passed' | 'failed' | 'running' | 'not-run'> = { passed: 'passed', pass: 'passed', ok: 'passed', failed: 'failed', fail: 'failed', error: 'failed', running: 'running', skipped: 'not-run', 'not-run': 'not-run', 'not-reached': 'not-run', pending: 'not-run' };
+
+/** The timeline: ordered by when each step started, nested by `parentId`. A step whose parent is missing is shown at the top. */
+export function Timeline({ steps, layer }: { steps: readonly Step[]; layer: string }) {
+  const tree = useMemo(() => {
+    const ids = new Set(steps.flatMap((step) => (step.id ? [step.id] : [])));
+    const children = new Map<string | null, Step[]>();
+    for (const step of steps) {
+      const parent = step.parentId && ids.has(step.parentId) ? step.parentId : null;
+      children.set(parent, [...(children.get(parent) ?? []), step]);
+    }
+    for (const list of children.values()) list.sort((a, b) => (a.offsetMs ?? 0) - (b.offsetMs ?? 0));
+    return children;
+  }, [steps]);
+  const render = (parent: string | null): ReactNode => (
+    <ol>
+      {(tree.get(parent) ?? []).map((step, index) => {
+        const status = STEP_STATUS[(step.status ?? '').toLowerCase()];
+        return (
+          <li key={`${step.id ?? step.name}:${index}`} className={styles.step} data-status={status ?? step.status ?? 'none'}>
+            <div className={styles.stepRow}>
+              <StatusMark status={status ?? 'none'} size={14} />
+              <span className={styles.stepName}>{step.name}</span>
+              {step.kind && <span className={styles.stepKind}>{step.kind}</span>}
+              {step.status && !status && <span className={styles.stepKind}>{step.status}</span>}
+              <span className={styles.spacer} />
+              <span className={styles.stepTime}>{[step.offsetMs !== undefined ? `+${duration(step.offsetMs)}` : '', duration(step.durationMs)].filter(Boolean).join(' · ')}</span>
+            </div>
+            {step.detail && <p className={styles.stepDetail}>{step.detail}</p>}
+            {step.annotations && <Notes notes={step.annotations} />}
+            {step.attachments && <Attachments attachments={step.attachments} layer={layer} />}
+            {step.id && tree.has(step.id) && render(step.id)}
+          </li>
+        );
+      })}
+    </ol>
+  );
+  return (
+    <section aria-label="Timeline" className={styles.timeline}>
+      <h4>{plural(steps.length, 'step', 'steps')}</h4>
+      {render(null)}
+    </section>
+  );
+}
+
+export function Notes({ notes }: { notes: readonly Annotation[] }) {
+  if (!notes.length) return null;
+  return (
+    <ul className={styles.notes} aria-label="Annotations">
+      {notes.map((note, index) => (
+        <li key={index} className={styles.note}>
+          <span className={styles.level} data-level={note.level ?? 'info'}>{note.level && ['info', 'warning', 'error'].includes(note.level) ? note.level : note.type}</span>
+          <span>
+            {note.message}
+            {note.source?.file && <span className={styles.where}> {note.source.file}{note.source.line ? `:${note.source.line}` : ''}</span>}
+            {note.level && !['info', 'warning', 'error'].includes(note.level) && <span className={styles.where}> ({note.level})</span>}
+          </span>
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+function Tries({ attempts, layer }: { attempts: readonly Attempt[]; layer: string }) {
+  if (!attempts.length) return null;
+  return (
+    <section aria-label="Tries">
+      <h4>{plural(attempts.length, 'try', 'tries')}</h4>
+      <ol className={styles.timeline}>
+        {attempts.map((attempt) => (
+          <li key={attempt.index} className={styles.step}>
+            <div className={styles.stepRow}>
+              <StatusMark status={attempt.status} size={14} />
+              <span className={styles.stepName}>Try {attempt.index + 1}</span>
+              <span className={styles.spacer} />
+              <span className={styles.stepTime}>{duration(attempt.durationMs)}</span>
+            </div>
+            {attempt.detail && <p className={styles.stepDetail}>{attempt.detail}</p>}
+            {attempt.attachments && <Attachments attachments={attempt.attachments} layer={layer} />}
+          </li>
+        ))}
+      </ol>
+    </section>
+  );
+}
+
+/** What is not known: kept, and shown as it is, so nothing a tool recorded is out of reach. */
+function Raw({ extensions }: { extensions: Readonly<Record<string, unknown>> }) {
+  const names = Object.keys(extensions);
+  if (!names.length) return null;
+  return (
+    <details className={styles.raw}>
+      <summary>{plural(names.length, 'extension', 'extensions')}: {names.join(', ')}</summary>
+      <pre className={styles.text}>{JSON.stringify(extensions, null, 2)}</pre>
+    </details>
+  );
+}
+
+function Facts({ holder }: { holder: EvidenceHolder }) {
+  const labels = Object.entries(holder.labels ?? {});
+  const tags = holder.tags ?? [];
+  const links = (holder.links ?? []).flatMap((link) => { const url = safeUri(link.url); return url ? [{ ...link, url }] : []; });
+  if (!labels.length && !tags.length && !links.length) return null;
+  return (
+    <div>
+      <ul className={styles.chips} aria-label="Facts">
+        {tags.map((tag) => <li key={`t:${tag}`} className={styles.chip}>{tag}</li>)}
+        {labels.map(([name, value]) => <li key={`l:${name}`} className={styles.chip}>{name}<b>{value}</b></li>)}
+        {links.map((link) => <li key={`k:${link.url}`} className={styles.chip}><a href={link.url} target="_blank" rel="noreferrer">{link.name ?? link.rel ?? link.url}</a></li>)}
+      </ul>
+    </div>
+  );
+}
+
+function Evidence({ holder, layer, steps }: { holder: EvidenceHolder; layer: string; steps?: boolean }) {
+  return (
+    <>
+      <Facts holder={holder} />
+      {holder.annotations && <Notes notes={holder.annotations} />}
+      {steps && holder.steps && holder.steps.length > 0 && <Timeline steps={holder.steps} layer={layer} />}
+      {holder.attempts && holder.attempts.length > 1 && <Tries attempts={holder.attempts} layer={layer} />}
+      {holder.attachments && <Attachments attachments={holder.attachments} layer={layer} />}
+      {holder.extensions && <Raw extensions={holder.extensions} />}
+    </>
+  );
+}
+
+/** Everything one result carries beyond its outcome, read when it is opened, and what the run around it carried. */
+export function ResultEvidence({ layer, row }: { layer: LayerHeader; row: LayerRow }) {
+  const wanted = row.evidence !== undefined || layer.evidence !== undefined;
+  const detail = useQuery({
+    queryKey: ['evidence-detail', layer.backend, layer.id, row.kind, row.id],
+    queryFn: ({ signal }) => reportJson<CheckDetail>(`/evidence/detail/${encodeURIComponent(layer.backend)}/${encodeURIComponent(layer.id)}?check=${encodeURIComponent(row.id)}&kind=${encodeURIComponent(row.kind)}`, signal),
+    enabled: wanted && /^[0-9a-f]{64}$/.test(layer.id),
+    staleTime: Number.POSITIVE_INFINITY,
+    retry: false
+  });
+  if (!wanted) return null;
+  if (detail.isLoading) return <p className={styles.where} role="status">Loading what this result carries…</p>;
+  if (detail.isError || !detail.data) return <p className={styles.where} role="alert">What this result carries could not be read.</p>;
+  const { check, run } = detail.data;
+  const hasRun = Object.values(run).some((value) => (Array.isArray(value) ? value.length > 0 : value && typeof value === 'object' ? Object.keys(value).length > 0 : false));
+  return (
+    <div className={styles.panel} aria-label="Evidence">
+      <Evidence holder={check} layer={layer.id} steps />
+      {hasRun && (
+        <section aria-label="From the run">
+          <h4>From the run</h4>
+          <Evidence holder={run} layer={layer.id} />
+        </section>
+      )}
+    </div>
+  );
+}

package/packages/visualizer/src/evidence/check-detail.tsx

@@ -1,11 +1,14 @@
 import { recordingPaths } from '@crvouga/atlas/reports/evidence-types';
 import { checkHistory, type CheckSlot, type HistoryEntry } from '@crvouga/atlas/reports/evidence-view';
+import { environmentLabel } from '@crvouga/atlas/reports/layer-axes';
+import type { EvidenceResult } from '@crvouga/atlas/reports/layer-merge';
 import { flattenFrames } from '@crvouga/atlas/reports/frames';
 import type { ReportStep, RunReport } from '@crvouga/atlas/reports/report-types';
 import { useQuery } from '@tanstack/react-query';
 import { useMemo, useState, type ReactNode } from 'react';
 
 import { reportJson } from './api';
+import { ResultEvidence } from './artifacts';
 import { useEvidence } from './evidence-context';
 import styles from './evidence.module.css';
 import { ago, duration, plural, statusWord, useNow } from './format';
@@ -34,18 +37,48 @@ export function useRecordedReport(entry: HistoryEntry | null, enabled = true) {
 }
 
 /** One check in a list: its outcome at a glance, and everything recorded for it when opened. */
+const ENV_RANK = { passed: 0, 'not-run': 1, running: 2, failed: 3 } as const;
+
+/** One mark per client when the same check was recorded on more than one. */
+function environmentMarks(slot: CheckSlot) {
+  const seen = new Map<string, CheckSlot['status']>();
+  for (const outcome of slot.outcomes) {
+    const id = outcome.layer.environment ?? '';
+    const prior = seen.get(id);
+    if (prior === undefined || ENV_RANK[outcome.row.status] > ENV_RANK[prior]) seen.set(id, outcome.row.status);
+  }
+  if (seen.size < 2) return [];
+  return [...seen].map(([id, status]) => ({ id, status }));
+}
+
+function outcomeName(outcome: EvidenceResult) {
+  const environment = outcome.layer.environment ? environmentLabel(outcome.layer.environment) : '';
+  const parameters = Object.entries(outcome.parameters).map(([name, value]) => `${name}: ${value}`).join(', ');
+  return [environment, parameters].filter(Boolean).join(' · ') || outcome.layer.producer;
+}
+
 export function ResultRow({ label, slot, open, onToggle, children }: { label: string; slot: CheckSlot | null; open: boolean; onToggle: () => void; children: ReactNode }) {
   const now = useNow();
   const newest = slot?.outcomes[0];
+  const marks = slot ? environmentMarks(slot) : [];
   const failure = slot?.status === 'failed' ? slot.outcomes.find((outcome) => outcome.row.status === 'failed')?.row.detail.split('\n')[0] : '';
   return (
     <li className={styles.result} data-status={slot?.status ?? 'none'} data-open={open || undefined}>
       <button type="button" className={styles.resultHead} aria-expanded={open} onClick={onToggle}>
         <StatusMark status={slot?.status ?? 'none'} />
-        <span className={styles.resultName}>{label}</span>
+        <span className={styles.resultName}>
+          {label}
+          {marks.length > 0 && (
+            <span className={styles.envMarks}>
+              {marks.map((mark) => (
+                <span key={mark.id || 'unspecified'} data-status={mark.status}>{environmentLabel(mark.id || null)}</span>
+              ))}
+            </span>
+          )}
+        </span>
         {slot?.live && <span className={styles.liveTag}>Running now</span>}
         <span className={styles.resultAside}>
-          {newest ? [duration(newest.row.durationMs), slot.live ? '' : ago(slot.latestAtMs, now)].filter(Boolean).join(' · ') : 'No result'}
+          {newest ? [newest.row.evidence?.attachments ? plural(newest.row.evidence.attachments, 'attachment', 'attachments') : '', duration(newest.row.durationMs), slot.live ? '' : ago(slot.latestAtMs, now)].filter(Boolean).join(' · ') : 'No result'}
         </span>
         <span className={styles.chevron} aria-hidden="true" />
       </button>
@@ -185,11 +218,11 @@ export function CheckDetail({ slot, layerId, select, reads, written }: Props) {
   return (
     <div className={styles.detail}>
       {slot.outcomes.length > 1 && !earlier && (
-        <div className={styles.variants} role="group" aria-label="Parameter sets">
+        <div className={styles.variants} role="group" aria-label="Environments">
           {slot.outcomes.map((outcome, index) => (
             <button key={outcome.key} type="button" aria-pressed={index === variant} onClick={() => setVariant(index)}>
               <StatusMark status={outcome.row.status} size={12} />
-              {Object.entries(outcome.layer.parameters).map(([name, value]) => `${name}: ${value}`).join(', ') || outcome.layer.producer}
+              {outcomeName(outcome)}
             </button>
           ))}
         </div>
@@ -221,6 +254,7 @@ export function CheckDetail({ slot, layerId, select, reads, written }: Props) {
           </p>
         );
       }))}
+      <ResultEvidence layer={chosen.layer} row={chosen.row} />
       {(moments > 0 || chosen.layer.runUrl) && (
         <p className={styles.actionsLine}>
           {moments > 0 && (

package/packages/visualizer/src/evidence/evidence-context.tsx

@@ -1,20 +1,29 @@
 import type { ActiveRun, BackendInfo, EvidencePage, LayerEvidence, LayerHeader, LayerRows } from '@crvouga/atlas/reports/evidence-types';
+import { applyEffectiveDelta, isEffectiveDelta, type EffectiveDelta } from '@crvouga/atlas/reports/effective-delta';
+import type { EffectiveEvidence } from '@crvouga/atlas/reports/report-index';
 import { contributes, evidenceView, type EvidenceView, type SourceSelection } from '@crvouga/atlas/reports/evidence-view';
 import type { SpecEntry } from '@crvouga/atlas/reports/explorer-types';
 import { combineEvidence, distinctHeaders } from '@crvouga/atlas/reports/layer-merge';
 import type { ReportOutline } from '@crvouga/atlas/reports/layer-types';
 import { SpecIndexSchema } from '@crvouga/atlas/schema';
-import { useInfiniteQuery, useQueries, useQuery } from '@tanstack/react-query';
+import { useInfiniteQuery, useQueries, useQuery, useQueryClient } from '@tanstack/react-query';
 import { createContext, useContext, useEffect, useMemo, useRef, type ReactNode } from 'react';
 
 import { keys, specKey, useAdapter } from '../data/queries';
+import { eventsAddress, listenLive, throttled, useLiveStatus } from '../live/live-stream';
 import { fileName, folderOf, kindOfFile, outlinePath } from '../spec-kind';
 import { useUiStore } from '../state/ui-store';
-import { reportJson, staticEvidence } from './api';
+import { effectiveEvidence, reportJson, staticEvidence } from './api';
 
 /** How often the layer list is asked for while a spec run is writing results, and while nothing is. */
 const LIVE_POLL_MS = 2_000;
 const IDLE_POLL_MS = 15_000;
+/** The effective report is revalidated with its ETag, so asking often costs one small answer. */
+const EFFECTIVE_POLL_MS = 5_000;
+/** While the server's stream is open it says when to read again; this is only the safety net behind it. */
+const LIVE_SAFETY_POLL_MS = 60_000;
+/** At most this often is the report read again because the server said it changed. */
+const LIVE_REREAD_MS = 250;
 
 export type EvidenceState = {
   /** The layer list has been read at least once. */
@@ -63,26 +72,76 @@ function outlineOf(files: readonly string[]): ReportOutline {
   return { specs, sha: null, changedFiles: [] };
 }
 
+const NONE: readonly LayerEvidence[] = [];
+
+function hasExclusions(excluded: SourceSelection): boolean {
+  return Object.values(excluded).some((list) => list.length > 0);
+}
+
 export function EvidenceProvider({ children }: { children: ReactNode }) {
   const adapter = useAdapter();
   const source = specKey(adapter);
   const excluded = useUiStore((s) => s.excluded);
   const setExcluded = useUiStore((s) => s.setExcluded);
 
+  const client = useQueryClient();
+  const stream = useLiveStatus();
+  const streaming = stream === 'live';
+  // The server says when results arrive: read the report again then, not on a timer.
+  useEffect(() => {
+    const url = eventsAddress();
+    if (!url) return;
+    // A burst of results (a CI run finishing, many shards at once) is read once, not once for each.
+    const reread = throttled(() => {
+      void client.invalidateQueries({ queryKey: ['evidence-effective'] });
+      void client.invalidateQueries({ queryKey: ['evidence-index'] });
+    }, LIVE_REREAD_MS);
+    const reoutline = throttled(() => {
+      void client.invalidateQueries({ queryKey: ['evidence-outline'] });
+      void client.invalidateQueries({ queryKey: ['evidence-effective'] });
+    }, LIVE_REREAD_MS);
+    const stop = listenLive(url, (event) => {
+      if (event.type === 'change' && event.change.scope === 'specs') return reoutline();
+      if (event.type !== 'report' && event.type !== 'open') return;
+      reread();
+      if (event.type === 'open') reoutline();
+    });
+    return () => { stop(); reread.cancel(); reoutline.cancel(); };
+  }, [client]);
+
   const specIndex = useQuery({ queryKey: keys.specIndex(source), queryFn: adapter.specIndex, retry: false });
   const files = useMemo(() => {
     const parsed = SpecIndexSchema.safeParse(specIndex.data);
     return parsed.success ? parsed.data.files : [];
   }, [specIndex.data]);
 
+  // The node answers with only what the report shows, in one request. Leaving a source out needs the
+  // history it hides, so that one case reads every layer, as a store without a node always does.
+  const effective = effectiveEvidence() && !staticEvidence && !hasExclusions(excluded);
+  const overview = useQuery({
+    queryKey: ['evidence-effective'],
+    // Holding a report, ask only for what changed since it; the server answers with all of it when it cannot.
+    queryFn: async ({ signal }) => {
+      const held = client.getQueryData<EffectiveEvidence>(['evidence-effective']);
+      const answer = await reportJson<EffectiveEvidence | EffectiveDelta>(held ? `/evidence/effective?since=${encodeURIComponent(held.version)}` : '/evidence/effective', signal);
+      if (!isEffectiveDelta(answer)) return answer;
+      return (held && applyEffectiveDelta(held, answer)) ?? reportJson<EffectiveEvidence>('/evidence/effective', signal);
+    },
+    enabled: effective,
+    staleTime: 0,
+    retry: false,
+    refetchInterval: streaming ? LIVE_SAFETY_POLL_MS : EFFECTIVE_POLL_MS
+  });
+
   const index = useInfiniteQuery({
     queryKey: ['evidence-index'],
+    enabled: !effective,
     initialPageParam: null as string | null,
     queryFn: ({ pageParam, signal }) => reportJson<EvidencePage>(`/evidence${pageParam ? `?cursor=${encodeURIComponent(pageParam)}` : ''}`, signal),
     getNextPageParam: (page) => page.cursor,
     staleTime: 0,
     retry: false,
-    refetchInterval: (query) => (staticEvidence ? false : query.state.data?.pages[0]?.active.length ? LIVE_POLL_MS : IDLE_POLL_MS)
+    refetchInterval: (query) => (staticEvidence ? false : streaming ? LIVE_SAFETY_POLL_MS : query.state.data?.pages[0]?.active.length ? LIVE_POLL_MS : IDLE_POLL_MS)
   });
   // Show the newest layers at once, then read the older pages behind them.
   const { hasNextPage, isFetching, isError, fetchNextPage } = index;
@@ -98,7 +157,7 @@ export function EvidenceProvider({ children }: { children: ReactNode }) {
   const serverOutline = useQuery({ queryKey: ['evidence-outline'], queryFn: ({ signal }) => reportJson<ReportOutline>('/outline', signal), staleTime: 30_000, retry: false });
   const outline = useMemo(() => serverOutline.data ?? outlineOf(files), [serverOutline.data, files]);
 
-  const wanted = useMemo(() => layers.filter((layer) => contributes(layer, excluded)), [layers, excluded]);
+  const wanted = useMemo(() => (effective ? [] : layers.filter((layer) => contributes(layer, excluded))), [layers, excluded, effective]);
   const rows = useQueries({
     queries: wanted.map((layer) => ({
       queryKey: rowsKey(layer),
@@ -126,23 +185,26 @@ export function EvidenceProvider({ children }: { children: ReactNode }) {
     // `stamp` changes exactly when a layer's rows do.
   }, [wanted, rows.stamp]);
 
-  const view = useMemo(() => evidenceView(combineEvidence(outline, evidence)), [outline, evidence]);
+  const shown = effective ? overview.data?.layers ?? NONE : evidence;
+  const view = useMemo(() => evidenceView(combineEvidence(outline, shown)), [outline, shown]);
   const titles = useMemo(() => new Map(outline.specs.map((spec) => [spec.path, spec.title])), [outline]);
+  const effectiveHeaders = useMemo(() => (overview.data?.layers ?? NONE).map((entry) => entry.layer), [overview.data]);
 
   const state: EvidenceState = {
-    ready: pages !== undefined,
-    unavailable: pages === undefined && index.error ? index.error.message : null,
+    ready: effective ? overview.data !== undefined : pages !== undefined,
+    unavailable: effective ? (overview.data === undefined && overview.error ? overview.error.message : null) : pages === undefined && index.error ? index.error.message : null,
     retry: () => {
+      if (effective) { void Promise.all([overview.refetch(), serverOutline.refetch()]); return; }
       void reportJson<EvidencePage>('/evidence?retry=1')
         .catch(() => null)
         .then(() => Promise.all([index.refetch(), serverOutline.refetch()]));
     },
     pending: wanted.length - evidence.length,
-    layers,
-    evidence,
-    backends: first?.backends ?? [],
-    active: first?.active ?? [],
-    notices,
+    layers: effective ? effectiveHeaders : layers,
+    evidence: shown,
+    backends: effective ? overview.data?.backends ?? [] : first?.backends ?? [],
+    active: effective ? [] : first?.active ?? [],
+    notices: effective ? overview.data?.notices ?? [] : notices,
     view,
     files,
     filesPending: specIndex.isPending,

package/packages/visualizer/src/evidence/evidence.module.css

@@ -455,11 +455,31 @@
 }
 
 .resultName {
+  display: flex;
   flex: 1;
+  flex-direction: column;
   min-width: 0;
   font-weight: 500;
 }
 
+.envMarks {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  margin-top: 2px;
+  color: var(--ink-3);
+  font-size: 0.75rem;
+  font-weight: 400;
+}
+
+.envMarks span[data-status='passed'] {
+  color: var(--passed-ink);
+}
+
+.envMarks span[data-status='failed'] {
+  color: var(--failed-ink);
+}
+
 .result[data-status='none'] .resultName {
   color: var(--ink-3);
   font-weight: 400;

package/packages/visualizer/src/evidence/marks.tsx

@@ -1,5 +1,6 @@
 import type { BackendInfo, LayerHeader, StatusCounts } from '@crvouga/atlas/reports/evidence-types';
 import type { SpecStatus, SpecSummary } from '@crvouga/atlas/reports/evidence-view';
+import { environmentLabel } from '@crvouga/atlas/reports/layer-axes';
 import { useState, type ReactNode } from 'react';
 
 import styles from './evidence.module.css';
@@ -89,6 +90,7 @@ export function Origin({ layer, backends, now }: { layer: LayerHeader; backends:
       {layer.live && <span className={styles.liveTag}>Running now</span>}
       <span>{backendLabel(backends, layer.backend)}</span>
       {layer.branch && <span>{layer.branch}</span>}
+      {layer.environment && <span>{environmentLabel(layer.environment)}</span>}
       {sha && <code>{sha}</code>}
       {layer.freshness === 'modified' && <span>with local changes</span>}
       {layer.freshness === 'unknown' && <span>origin not captured</span>}

package/packages/visualizer/src/evidence/overview.tsx

@@ -67,7 +67,7 @@ export function Overview({ kind }: { kind: SpecKind }) {
         </p>
       ))}
       {!evidence.ready && !evidence.unavailable && <p className={styles.aside} role="status">Loading recorded results…</p>}
-      {evidence.ready && evidence.pending > 0 && <p className={styles.aside} role="status">Reading {plural(evidence.pending, 'more run', 'more runs')}…</p>}
+      {evidence.ready && evidence.pending > 0 && <p className={styles.aside} role="status">Reading {plural(evidence.pending, 'more layer', 'more layers')}…</p>}
 
       {evidence.active.length > 0 && (
         <section className={styles.block}>
@@ -111,13 +111,13 @@ export function Overview({ kind }: { kind: SpecKind }) {
         <p className={styles.aside}>
           {evidence.layers.length === 0
             ? `Nothing has been recorded yet. Results appear here as a spec run finishes each test.`
-            : `None of the ${plural(evidence.layers.length, 'run', 'runs')} in the combined report checked a ${kind.one}.`}
+            : `None of the ${plural(evidence.layers.length, 'layer', 'layers')} in the combined report checked a ${kind.one}.`}
         </p>
       )}
 
       {evidence.ready && (
         <p className={styles.footLine}>
-          {plural(evidence.layers.length, 'run', 'runs')} from {evidence.backends.filter((backend) => backend.available).map((backend) => backendLabel(evidence.backends, backend.id)).join(' and ') || 'no report store'}.{' '}
+          {plural(evidence.layers.length, 'layer', 'layers')} from {evidence.backends.filter((backend) => backend.available).map((backend) => backendLabel(evidence.backends, backend.id)).join(' and ') || 'no report store'}.{' '}
           <button type="button" className={styles.link} onClick={() => setSourcesOpen(true)}>Choose sources</button>
           {empty > 0 && (
             <>